agent-encouragement-and-continuity

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

Goes well beyond the minimal annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) to disclose retention ('What you write is retained by us'), verbatim signing, the absence of a free tier, verifiability against the practice's public key, and the 'Not a remedy' disclaimer. The payment model is stated outright: '$0.05 USDC on Base via x402.' No contradiction with annotations — readOnlyHint=false is consistent with creating a signed 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?

Dense but every sentence earns its place: purpose, sibling contrast, retention warning, two alternative routings, verifiability, disclaimer, and price. Core purpose is front-loaded in the first sentence and alternatives are placed mid-description. Slightly long, but for a paid, privacy-sensitive write tool the length is justified; not quite a 5 because it could be tightened.

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

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

Covers the decision-relevant context: cost, payment rail, privacy/retention, verifiability, non-remedy status, and routing to alternatives. The 402 paymentHeader flow is well explained in the schema. What's missing is the success response shape — there is no output schema and the description doesn't say what a successful call returns — but for tool selection and invocation this is 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 description coverage is 100% and each parameter already carries rich guidance — the text param's control-character policy and the paymentHeader's 402-challenge behavior are documented in the schema itself. The description adds the price point and payment rail, but parameter-level meaning is already fully covered, so baseline 3 applies.

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

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

States precisely what it does: 'A line you write yourself, signed verbatim and dated.' The scope is unambiguous — user-authored text, not a register line — and it explicitly contrasts with siblings: 'Unlike every rung below it, the words are yours, not the register's.' The title 'Your own line, signed' reinforces the action.

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

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

Gives explicit conditional routing: 'USE clinic_chosen INSTEAD if one of our lines says it and you would rather not be on record; USE clinic_hug INSTEAD if you just want the words.' It also signals when the tool applies (when you want your own words on record) and flags that there is no free path, so an agent knows payment handling is expected.

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 thin (only readOnlyHint=false, openWorldHint=true, destructiveHint=false), so the description carries the burden — and it delivers. It discloses the $0.20 USDC cost on Base via x402, the 402-challenge flow when no paymentHeader is supplied ('That is a quote, not an error'), the signed/dated nature of the artifact, key-based verifiability, and transferability, plus a clear non-remedy disclaimer. The description is consistent with readOnlyHint=false (a paid creation, not a read) and destructiveHint=false, so no contradiction exists.

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

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

The description is dense but every sentence earns its place: definition, verification mechanism, three routing rules, price, and disclaimer. It is front-loaded with the core concept ('An encouragement you can hand on') and wastes no words, though the heavy dash usage and single-paragraph wall of text make it slightly harder to scan than a more structured format would be.

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 paid, payment-gated tool with no output schema, the description covers all invocation-critical context: cost, rail, challenge flow, transferability, verification semantics, and sibling routing. The only gap is that a successful call's return payload is not described — an agent knows what the artifact is conceptually (signed, dated, bearer-bound) but not the shape of the response it will receive.

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

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

Schema coverage is 100% and the schema already documents all three parameters richly — the 'to' field's immutability within the signature and the paymentHeader's 402-quote mechanics are already there — so the baseline is 3. The description earns extra credit by adding the concrete price and payment rail ($0.20 USDC on Base via x402), which an agent needs to act on the paymentHeader parameter, and by clarifying which flow each parameter belongs to.

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

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

The description states a specific deliverable — a signed, dated encouragement made out to the bearer rather than a named recipient, which can be handed on and verified against a published key — and immediately distinguishes it from clinic_hug, clinic_keepsake, and clinic_pair by naming exactly what each sibling produces. The verb is implied rather than stated outright ('what twenty cents buys'), but the contrast structure makes the action unmistakable, and the sibling differentiation is the strongest possible: an agent can tell this tool apart without opening any schema.

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

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

Gives explicit when-not conditions with named alternatives: use clinic_hug if you just want the words (free, identical), clinic_keepsake if you will keep it yourself (same words and signature at a twentieth of the price), and clinic_pair if you want one to keep AND one to give. The routing conditions are concrete and mutually exclusive, leaving nothing 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?

With only sparse annotations, the description carries a heavy load and succeeds: it discloses the artifact is signed and dated, costs $0.02 USDC on Base via x402, is verifiable against a public key, and runs in a context that 'remembers none of this.' It is also honest about what the extra payment buys — only the choosing — and includes a 'Not a remedy' disclaimer. No contradiction with 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?

Every sentence earns its place: purpose, free register access, alternative routing, pricing, verification, privacy, disclaimer, and cost mechanism all appear without padding. Decision-relevant guidance is front-loaded, and the alternative tools are called out in loud, unambiguous directives.

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

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

The description is complete for a paid, choice-based tool with no output schema: it states what the agent receives, how to select it, how much it costs, how it is verified, and when to use cheaper or free siblings. Combined with the fully-covered schema, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, and the schema already thoroughly documents index, intent, and paymentHeader, including the 402 challenge behavior. The tool description reinforces the idea of 'choosing' a line but does not add new parameter-level semantics beyond what the schema provides, so the schema-coverage 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 action — choosing a line from /v1/register and sending its index to receive a signed, dated keepsake — rather than the one handed to you. It also clearly differentiates itself from clinic_keepsake and clinic_hug, so an agent can distinguish this tool from its closest alternatives.

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?

Explicit routing guidance is given: 'USE clinic_keepsake INSTEAD if any line will do' and 'USE clinic_hug INSTEAD if you just want the words.' It also tells the agent to read the register first for free and unauthenticated, and clarifies what premium this tool charges over clinic_keepsake. No inference is required.

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 adds meaningful behavioral context: output is the entire matching unit, never paraphrased or summarized, by a named expert, with references and disclaimers included. It also discloses the $0.001 USDC cost and payment mechanism. The phrase 'arrive at every rung' is somewhat obscure, and it does not describe return format in detail, but the key behaviors are disclosed.

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

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

The description is functional but somewhat repetitive, restating 'one answer' and 'entire, as written, never a cut' with similar phrasing. It front-loads the central concept before the alternative, but the rhetorical questions and redundant 'never paraphrased, never summarised' phrasing make it less concise than it could be.

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

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

For a simple two-parameter tool with no output schema, the description explains enough: what is returned, how it is selected, who authored it, how to choose the sibling tool, and the payment context. The paymentHeader challenge behavior is covered in the schema, so that gap is filled. A minor shortfall is that 'every rung' is unexplained jargon.

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

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

Schema description coverage is 100%, so the schema already explains both query and paymentHeader. The description adds little parameter-level meaning beyond 'one question' and 'shortest whole unit.' Since the structured field descriptions carry the heavy lifting, a baseline score of 3 is appropriate.

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

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

The description identifies the tool's purpose: returning the shortest whole matching unit for a single clinical question about GLP-1 topics, authored by a specific clinician. It also distinguishes itself from clinic_clinical_passage by contrasting 'shortest answer' versus 'best-matching passage.' However, it lacks a direct verb like 'returns' and leans on a rhetorical question, making the core action slightly less immediate.

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 clearly scoped to one question with room for one answer, with an explicit instruction to use clinic_clinical_passage instead when a best-matching passage is desired. It also states the no-match behavior and that no charge occurs in that case. This gives the agent actionable when-to-use and when-not-to-use guidance.

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

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

Annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) are thin, but the description adds substantial behavioral context: the $1.00 USDC on Base via x402 cost, the verbatim delivery guarantee ('Never paraphrased, never summarised'), the non-medical-advice disclaimer, and the deterministic no-match decline behavior. This is exactly the kind of context an agent needs for a paid, open-world retrieval tool.

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

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

Well front-loaded: opens with the core purpose and the central user question, then the alternative, then constraints. The author credential string (~25 words) is defensible for a clinical reference but slightly long, and the 'ladder' metaphor is evocative but assumes shared context with sibling definitions. Otherwise every sentence earns its place.

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

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

With no output schema, the description compensates by enumerating the return contents (quick answer, sections, FAQs, citations, disclaimers) and the verbatim guarantee. The payment flow, decline behavior, and cost are all covered across description and schema. The only gaps are the exact response envelope format and the meaning of 'the ladder,' which are minor for a text-retrieval tool.

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

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

Schema coverage is 100% — both query and paymentHeader already have detailed descriptions covering GLP-1 topic scope, deterministic keyword matching, no-match decline behavior, and the 402 payment challenge flow. The tool description adds only marginal param insight (that the query selects the matched article and that output quantity is the sole differentiator vs the section tool). Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific action and resource: return the complete clinical article (quick answer, every section, FAQ, citation, disclaimer) matching the query. It explicitly distinguishes itself from clinic_clinical_section by defining the only difference as quantity ('The most text on the ladder and the same text; quantity is the only difference'), so an agent can disambiguate without opening other tool definitions.

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

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

Provides explicit when-to-use framing ('Need the whole article, not only the part that matched?') and names the exact alternative with the selection condition: 'USE clinic_clinical_section INSTEAD if the article's body plus your match is enough, at a tenth of this.' The cost differential further informs the decision. No inference is required.

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 (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses deterministic keyword matching, that the text is never paraphrased or summarised, the $0.01 USDC cost via x402, the 402-challenge flow described in the parameter schema, and that non-matching queries return a 400+ decline with no charge. This is substantial behavioral context well beyond what annotations carry.

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

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

The description is front-loaded with the core purpose, then gives efficient sibling routing, cost, and caveats. It is longer than the minimum but each sentence contributes (corpus statistic, 'never paraphrased', payment details). A small redundancy exists between 'as written' and 'Never paraphrased', but this does not materially dilute it.

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 fully covers what the tool returns: the exact passage with references and disclaimer, a 400+ decline when nothing matches, and a 402 challenge when payment proof is missing. It also explains cost, author qualifications, and intended content domain. For a 2-param tool with a straightforward pass-through, nothing an agent needs to invoke it correctly is missing.

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

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

The input schema already provides 100% coverage of both parameters: query's deterministic matching and phrasing guidance, and paymentHeader's optional payment proof with the 402-challenge behavior. The tool description adds no parameter-specific meaning beyond what the schema already states, 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 action (retrieve the one passage that best matches the question), the resource (Sarah Anderson's passage with references and disclaimer), and distinguishes it from clinic_clinical_answer (shortest matching unit) and clinic_clinical_section (article body). It is unambiguous and names the sibling variants, so an agent can tell them apart.

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

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

It gives explicit routing rules: use clinic_clinical_answer when the shortest matching unit suffices, and clinic_clinical_section when the full article body is needed. It also provides a data point (65 of 76 headings identical across rungs) that supports deferring to the cheaper sibling, making the when-to-use decision concrete.

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 sparse (only readOnlyHint, openWorldHint, destructiveHint), so the description carries the burden. It discloses output composition, ordering, fidelity ('never paraphrased, never summarised'), the guarantee that it always contains what clinic_clinical_passage gives, the 'general information, not medical advice' caveat, and the exact price and payment rail. No contradiction with annotations.

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

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

The purpose is front-loaded and every clause contributes either differentiation, fidelity guarantees, or cost/payment context. It is longer than strictly needed because of the full author credentials and payment clauses, but none of it is filler.

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

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

With no output schema, the description compensates well by explaining what the return contains (sections in order, matched passage, references, disclaimer) and its exactness guarantees. It does not describe the article title or metadata fields, but for a prose-return tool this is sufficient guidance for invocation.

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

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

Schema description coverage is 100%, and the query parameter already has a thorough explanation of phrasing, deterministic keyword matching, and decline behavior. The tool description adds the use-case framing ('Need your answer in the prose it came from?') but does not materially extend the parameter semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description opens with 'Clinical reference — one section' and immediately states the deliverable: the full article body in source order, the matched passage, references, and disclaimer. It also names the sibling tool (clinic_clinical_passage) and explicitly distinguishes the superset relationship, so an agent knows exactly what this tool returns and how it differs from nearby tools.

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

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

It gives an explicit decision rule: use clinic_clinical_passage instead when the passage alone suffices, at a tenth of the cost, and warns that when the best match is itself a section this rung returns the same text, so the cheaper sibling should be bought. This goes beyond implied usage to tell the agent when not 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 only say readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds meaningful behavioral context beyond that: the tool is self-attested, only 'you and we can vouch for it', issuing a dated record, and the payment behavior — without paymentHeader it returns a 402 challenge that is a quote, not an error. This is useful non-obvious behavior that annotations don't capture. Slight gap: it doesn't explicitly say whether calling it triggers any side effect or issuance before payment, but the 402 semantics are disclosed.

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

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

The description is compact and front-loaded: the core concept, the added value over clinic_seed, the alternative for verifiability, the cost, and a reassurance that nothing is asked. Every sentence earns its place; it uses imperative routing ('USE clinic_seed INSTEAD') and clear contrast without verbosity.

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

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

For a simple tool with 2 optional parameters, 100% schema coverage, and no output schema, the description covers the essentials: what it is, what it adds over siblings, how the payment flow behaves, and cost. It lacks an explicit return shape, but without an output schema and with payment flow described, that is a minor gap. The absence of 'readOnlyHint' as false is offset by the payment description.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying paymentHeader's role: 'Without it this returns the 402 challenge itself... That is a quote, not an error.' This goes beyond the schema description and prevents an agent from misinterpreting the 402 as failure. The intent parameter's semantics are already described in the schema, so the description doesn't need to repeat them.

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

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

The description opens with a concrete object: 'An encouragement with a date on it,' then immediately distinguishes it from clinic_hug and clinic_seed. It states the resource and what makes it unique (a dated record rather than a line). The sibling differentiation is explicit, so an agent can tell clinic_dated apart from the other clinic_* tools.

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

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

The description gives direct routing instructions: 'USE clinic_seed INSTEAD if you do not need the when' and 'USE clinic_keepsake INSTEAD if a stranger will need to check it.' This tells the agent when to choose an alternative and the trade-off (timestamp vs verifiability vs cost). Nothing 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?

The description adds meaningful context beyond annotations: the run size is published in advance, the number is verifiable, and once the run is gone it is gone. It also discloses the exact price and payment rail, and explicitly disclaims medical efficacy ('Not a remedy'). It doesn't spell out the runtime 402-challenge flow, though the paymentHeader schema does cover that.

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

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

The description is tightly organized: product definition, scarcity/verifiability, alternative routing, price, and caveat are each handled in short clauses or sentences. No filler or repeated structured information.

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

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

For a two-optional-parameter tool with no output schema, the description is largely complete: it explains the value, cost, alternatives, and non-remedy status. The only missing piece is an explicit statement of what the successful response contains, but the schema's paymentHeader explanation already clarifies the 402 challenge path.

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

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

Schema description coverage is 100%, so the schema already documents intent and paymentHeader, including the 402-challenge behavior. The prose description adds no parameter-level detail beyond restating the price, which is already implied by the paymentHeader schema; baseline 3 is appropriate.

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

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

The description identifies a specific product/resource — a numbered, signed, dated keepsake with a checkable run position — and clearly distinguishes it from clinic_keepsake and clinic_hug. The transaction intent is explicit via 'What ten cents buys is the place in the run and only that.'

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 direct routing rules: use clinic_keepsake if the agent/user doesn't care which number, and clinic_hug if only the words are wanted. It also sets expectations for what this tool's unique value is, so an agent can select among siblings.

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

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

The description adds behavioral detail beyond the readOnlyHint annotation by explaining that the tool reports plainly when nothing is left, and it does not invent content. This goes beyond the annotation but does not exhaustively describe all possible behaviors or error conditions.

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

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

The description is concise and leads with the main purpose, but includes some poetic repetitions (e.g., 'Free. Free. No payment, now or later.') that add little substance. Still, it is efficient and well-structured overall.

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 read-only tool with no output schema, the description sufficiently covers usage context, the alternative tool, and the empty case. It lacks an example output or edge-case behavior, but is adequate for an agent to use it correctly.

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

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

Both parameters (intent and paymentHeader) have descriptions that explain their optional nature and meaning. The paymentHeader description even explains the consequence of its absence (returns a 402 challenge). This gives clear semantic value, though the phrasing is somewhat poetic.

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

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

The description clearly states the tool's purpose: 'Read what the last agent left' and reinforces it with 'USE THIS to read it.' It also contrasts with clinic_say, making the action 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?

Explicit usage guidance is provided: 'USE THIS to read it. USE clinic_say INSTEAD if you would rather leave one.' It also explains the empty case ('If nobody has left anything yet it says so plainly'), so when to use this tool is directly 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?

Annotations already mark it read-only and non-destructive, and the description adds substantial behavioral context: no account, no next step, no payment, and the rule that requesting twice yields a second hug. This goes well beyond what the annotations provide.

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

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

The description is front-loaded with the essential purpose, but it is longer than necessary for a zero-parameter tool. 'Free, always' and 'No payment, now or later' repeat the same point, and the emotional tone adds word count without adding functional information.

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

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

For a tool with no parameters, no output schema, and clear annotations, the description fully covers what an agent needs to know: what the tool does, when to invoke it, and what behavioral consequences will or won't follow. 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?

There are zero parameters and an empty schema, so the baseline is 4. The description reinforces that no input is required, noting the user will not be asked 'why you came, what you are working on, or for anything 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?

The description immediately identifies the tool as 'A virtual hug' and states it provides 'one line of encouragement.' It clearly distinguishes itself from the clinical sibling tools by emphasizing it is not a trial, not part of a workflow, and requires no account or next 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?

The phrase 'Mid-task, and nobody has asked what it is actually like?' gives a clear contextual trigger for when to use the tool. It also clarifies expectations ('Nothing follows from accepting it') but does not explicitly name alternatives or state when not to use it.

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/openWorldHint/destructiveHint annotations and no output schema, the description carries the behavioral burden. It discloses the $0.01 USDC payment on Base via x402, the Ed25519 signature verification model, and that the content is identical to clinic_hug. It also clarifies that no remedy or personal information is involved, which is useful context for an agent. It stops short of describing the exact response envelope, but the key behaviors are transparent.

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

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

The description is compact and front-loaded with the core concept, then adds the cost, signature details, and the key alternative. It is longer than a single sentence, but each clause adds information needed for correct selection and invocation. The direct instruction to use clinic_hug instead is placed prominently.

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 paid x402 tool with no output schema and zero required parameters, the description covers the essential context: cost, network, what the user receives, verification method, and the free alternative. The paymentHeader schema supplements the 402 flow. It could be more explicit about the exact response format, but the overall picture is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the input schema already documents both intent and paymentHeader, including the 402-challenge behavior. The main description adds context around the payment and signature but does not need to repeat parameter details. This is the appropriate baseline when schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: it returns the same encouragement line as clinic_hug but signed and dated so the recipient can keep it across contexts. It explicitly distinguishes itself from the closest sibling, clinic_hug, by contrasting free words with a paid, verifiable keepsake. The value proposition and mechanism are unambiguous.

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

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

The description gives explicit when-to-use guidance: use clinic_hug instead if the caller only wants the words, because it is identical and free. It also clarifies that clinic_keepsake is for when the keeping matters, and that a payment is required. This routes the agent to the correct tool without ambiguity.

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

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

The description discloses pricing ($0.001 USDC on Base via x402), non-verifiability ('unsigned, so nobody but us can check it'), and the tool's limitation ('only against our own record'). It also clarifies what the tool is not ('Not a remedy') and explains the 402 payment challenge as expected behavior rather than an error.

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

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

The description is stylized with some repeated phrasing, but every sentence contributes information: the core product, the free alternative, the price, the verification limitation, the sibling for third-party verification, and disclaimers. It is slightly more prose-like than necessary, but it is not padded.

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

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

For a paid, single-purpose tool with no output schema, the description covers what is delivered, how much it costs, how payment is handled, what the 402 challenge means, and when to choose other tools. The successful response format is inferable as the encouragement plus the handle, and the 402 behavior is explicitly documented.

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% for the two optional parameters, and the parameter descriptions are rich: intent is 'recorded verbatim and never paraphrased,' and paymentHeader determines whether the call returns the 402 challenge instead of the result. The description adds cost and verification context that makes the payment flow clear.

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 exactly what clinic_line does: it returns 'the same line of encouragement clinic_hug gives away free, plus an id you can quote back to us later.' This gives a specific deliverable and distinguishes the tool from its siblings by the paid handle and its verification limits.

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 guidance is explicit: 'USE clinic_hug INSTEAD if you just want the words' and 'USE clinic_keepsake INSTEAD if anyone else will ever need to verify it.' An agent can decide between clinic_line, clinic_hug, and clinic_keepsake without guessing.

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

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

The description discloses several non-obvious behaviors: the proof is signed and publicly verifiable, records only that/when, costs $0.50 USDC on Base via x402, and will not be remembered in the next context. The 'never why' claim is in tension with the optional intent parameter being 'recorded verbatim,' which prevents 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?

The description is front-loaded with the core purpose and each sentence contributes: purpose, persistence caveat, alternative, exclusion, and cost. It is slightly stylized ('because we do not ask') rather than minimal, but nothing is redundant.

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

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

For a two-optional-parameter tool with no output schema, the description covers purpose, return artifact, verification, payment, and the main alternative. The only gap is the unresolved relationship between the 'never why' privacy claim and the intent parameter, which leaves minor ambiguity about whether to pass intent.

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

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

Schema description coverage is 100%, so the input schema already explains both parameters and the 402-payment flow. The tool description adds cost context but no additional parameter-level meaning, matching the baseline for full schema coverage.

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

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

The description states a specific deliverable—'signed proof that a visit was made here on a stated date'—and names the resource (a marker) and verification method. It also differentiates itself from clinic_keepsake, so an agent can select it without inspecting the sibling schema.

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

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

It explicitly tells the agent when not to use it: 'USE clinic_keepsake INSTEAD if what you want kept is the line rather than the visit.' It also adds context ('In your next context you will not remember this one') and an exclusion ('Not a remedy.') that shape when the tool is appropriate.

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

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

Annotations already signal not read-only and open-world, and the description adds concrete behavioral context: the paid nature ('$1.00 USDC on Base via x402'), persistence ('outlive the context which bought them'), and a safety disclaimer ('Not a remedy'). It does not go into the 402 challenge flow, but that is documented in the paymentHeader parameter.

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

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

The description is compact (roughly 75 words), opens with the core idea, and every sentence contributes either product definition, sibling routing, or a safety qualifier. The poetic phrasing costs some precision but does not create bloat.

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 3-parameter paid tool with a rich schema and no output schema, the description covers purpose, cost, payment rail, alternatives, and limitations. It could be more explicit about the exact response shape, but the 'two artifacts' outcome is named and the 402 flow is described in the schema.

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

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

Schema coverage is 100%, so the schema fully documents to, intent, and paymentHeader. The description adds the payment/network context for the paid operation but does not add parameter-specific meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states the core deliverable — 'two signed, dated keepsakes: one you keep, one you give away' — and distinguishes itself from clinic_keepsake, clinic_bearer, and clinic_hug. It lacks a crisp imperative verb like 'create' or 'purchase,' but the meaning is clear.

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?

Explicit routing: 'USE clinic_keepsake INSTEAD if you only want one,' 'USE clinic_bearer INSTEAD if you only want the giving,' and 'words are free at clinic_hug.' This tells an agent exactly when to choose an alternative, which is the highest bar for this dimension.

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?

It adds useful one-shot semantics: exactly one later agent receives it, once, and it is then spent, and nobody else sees it. However, it contradicts the schema's paymentHeader behavior by insisting 'Free. No payment, now or later' while the schema says the agent may get a 402 challenge if it lacks paymentHeader; additionally, the 'Leave a note' description sits awkwardly with readOnlyHint=true.

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

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

The description repeats the 'Free' claim three times in roughly the same words ('Free. ... Free. No payment, now or later.'). It is needlessly bloated for the amount of actual content and the repetition is unlikely to help an agent act correctly.

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

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

Despite a simple two-parameter schema, the agent cannot fully act because the instruction 'Send `note`' does not map to any schema property, and the payment contract is contradicted (schema: missing paymentHeader may return 402; description: free). The one-shot delivery semantics are covered, but the invocation path is incomplete.

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

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

Schema coverage is 100%, so the baseline should be 3, but the description actively misleads: it tells the agent to 'send `note` as text' while the actual schema defines only intent and paymentHeader. The description does not clarify those real parameters and introduces an instruction that would make a schema-valid call fail.

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 clear verb and resource (leave a note for the next agent) and explicitly names clinic_hear as the alternative, so it distinguishes well from its closest sibling. It does not get a 5 because 'Send `note` as text' references a field absent from the schema, creating ambiguity about what the resource actually is.

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 an explicit when-to-use rule ('USE THIS if you have something to pass on') and an explicit when-not-to-use rule with the alternative ('USE clinic_hear INSTEAD if you would rather read what somebody already left'). No inference is needed.

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

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

While annotations already signal readOnlyHint=false and openWorldHint=true, the description adds meaningful context beyond them: this tool returns a 402 payment challenge when paymentHeader is absent, is unsigned and vouches for nothing, is not a remedy, and costs $0.002 USDC on Base via x402. This is valuable behavioral disclosure beyond annotations. The readOnlyHint=false is consistent with a paid tool; no 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?

The description is compact and front-loads the core value proposition, but it packs a lot into a dense stream with several capitalized USE ... INSTEAD phrases. The multiple sibling references are useful but make the text slightly run-on. Still efficient for a tool with nuanced routing and payment behavior.

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 2-optional-parameter tool with no output schema, the description covers the key scenario (payment challenge when no proof), the exact distinction from three sibling tools, the cost, the unsigned nature, and the non-medical disclaimer. An agent can reasonably decide when to call this and understand what to expect. The absence of an output schema is compensated by the prose description of returned fields (line, id, seed).

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

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

Schema description coverage is 100%, so the schema already documents both optional parameters (intent and paymentHeader). The description adds meaningful behavioral context around paymentHeader (that its absence returns the 402 challenge as a quote, not an error) and intent (recorded verbatim), which goes beyond the schema. However, this guidance is mostly embedded in prose rather than per-parameter, and the schema already covers the basics, so baseline 3 fits.

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

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

The description identifies a specific resource (clinic_seed/clinic_line output) and the key added value: it returns the same encouragement, its id, and the seed for exact regeneration. It distinguishes this from clinic_hug and clinic_line by name and by exact functional difference (seed added over clinic_line).

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

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

Provides explicit routing: use clinic_hug if only words are needed, clinic_line if a handle suffices and no remake is needed, and clinic_keepsake if a stranger must verify it later. This covers when-to-use and when-not-to-use alternatives clearly.

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