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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context by disclosing the mechanism behind continuity, namely the persisted cookie jar, which explains why a resumable verdict depends on prior state.

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 with the two reported facts front-loaded and the mechanism stated last. Every sentence earns its place and nothing is 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?

There is no output schema, so the description reasonably names the two things reported (resumability and pending verification), but it does not specify the concrete return shape. For a zero-parameter status probe with full annotation coverage, this is nearly 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; per the baseline this scores 4. No misleading parameter claims are made.

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: it reports session resumability and pending-verification state. That is clearly distinct from the write-oriented siblings mah_sign_in, mah_send_verification_code, and mah_verify_code, though it never names them explicitly.

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 rather than stated: an agent is meant to call this before attempting to resume a session, or when it needs to know if a verification step is outstanding. No when-not condition or alternative tool is named, so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds only the content names (header, action plans) and says nothing about auth requirements, freshness, or how the summary relates to the underlying list tools, leaving behavioral context thin.

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 front-loaded sentence with no filler. It is efficient, though arguably too terse for a tool whose output shape is only implied.

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 carries the burden of describing returns but only names two content areas. The parameter is well covered in the schema, but an agent still lacks detail on what the summary contains or how it differs from assembling the list 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 description coverage is 100% and the single 'view' parameter is documented exhaustively in the schema, including enum semantics and per-reader stripping behavior. The description adds nothing about the parameter, 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?

States a specific verb (Fetch) and resource (MyAtriumHealth health-summary header and action plans), so an agent can tell it is a summary/header reader rather than one of the mah_list_* record readers. It stops short of naming a sibling or explicitly contrasting with mah_get_patient_context, so it lacks true sibling differentiation.

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 and no mention of alternatives. An agent gets no signal on when to prefer this over mah_get_patient_context or the individual mah_list_* readers that feed the same summary.

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=true, so the safety profile is covered. The description adds a real behavioral signal with 'Confirmed with the portal rather than reported from memory', implying a live freshness/verification guarantee rather than a cached value, though the wording is loose enough to leave the exact provenance ambiguous. It says nothing about authentication state, which siblings such as mah_sign_in and mah_auth_status suggest is relevant.

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

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

Two short sentences with no padding, and the subject (which patient) is front-loaded. The second sentence earns its place by adding provenance, though the missing verb makes the opening feel clipped rather than crisp.

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, no parameters, and only two annotations, the description carries most of the burden. It conveys the concept of an active-patient context but never states what is actually returned (an identifier, a name, demographics) or under what conditions it would be empty or fail, leaving a real gap for a tool with no structured return definition.

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. The description correctly does not invent parameter discussion, and the empty schema leaves nothing for it to compensate for.

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 resource ('which patient the reading tools are currently returning data for') but frames it as a noun clause rather than a verb+resource statement, so it never says the tool 'gets' or 'returns' anything. It is distinguishable from siblings like mah_list_patients and mah_set_active_patient, but an agent has to infer the action from context.

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 explicit when-to-use, when-not-to-use, or alternative routing. The phrase 'the reading tools' weakly implies you would consult this before/while reading patient data, but the agent is never told to call it for that reason or how it relates to mah_set_active_patient.

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 the safety profile (readOnlyHint, idempotentHint, openWorldHint), and the description still adds substantial value: it enumerates the two distinct modes, the exact diagnostic fields returned (bridge role, port, version, link state, RTT), and explicit guarantees ("no auth required", "never returns the credential itself"). This is a genuinely helpful disclosure layer beyond the structured fields.

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 and mode labels are front-loaded ("Relaying through your signed-in browser tab" / "Signing in server-side with configured credentials"), so the dense text is navigable. It is long, but nearly every clause adds a distinct diagnostic fact rather than restating 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?

With no output schema, the description carries the full burden of explaining returns, and it does so thoroughly: it lists the diagnostic fields and the plain-English hint categories for both paths. An agent knows what it will get back and how to interpret each branch.

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 and there is no parameter syntax the description needs to compensate for. Nothing in the description muddies the parameterless contract.

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 opening sentence states a specific verb and outcome ("Reports which hop is broken when a real tool fails"), and the two paragraphs spell out exactly which connectivity paths are exercised. It is unambiguous what the tool does, though it never names the closest sibling (mah_auth_status) to differentiate itself explicitly.

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 clearly stated ("when a real tool fails"), which tells the agent exactly when to reach for it. What is missing is the when-not side and any explicit routing versus mah_auth_status, 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 already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered elsewhere. The description adds no behavioral context of its own: it doesn't mention the auth/active-patient prerequisite that this multi-tool health portal clearly has (mah_sign_in, mah_set_active_patient), nor ordering, pagination, or empty-result 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?

One sentence, front-loaded with the verb and resource, with zero filler. Nothing is padded or 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 read-only list tool with annotations covering safety and a fully documented single parameter, the description is nearly sufficient. However, with no output schema and clear auth/patient-context dependencies in this tool family, the omission of any prerequisite or result-shape note leaves a real gap.

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 single "view" enum is documented in exhaustive detail in the schema, including the fact that this tool is one of the projection-derived readers. Baseline 3 is correct: the description adds nothing about "view" or record shaping.

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?

Concrete verb ("List") plus a specific resource (allergies and their reactions) and an explicit data source (the MyAtriumHealth health summary). An agent can distinguish it at a glance from most siblings such as mah_list_medications or mah_list_immunizations, though no sibling is named and the overlap with mah_get_health_summary is not addressed.

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?

No when-to-use guidance, no precondition (e.g., signed-in / active-patient requirement) and no alternative named. The only hint is the phrase "from the MyAtriumHealth health summary," which just restates the source rather than telling the agent when this reader is the right choice over mah_get_health_summary.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely useful return-shape context: results are bucketed into outstanding / zero-balance / guarantor-authorized, and monetary values come back as pre-formatted display strings rather than raw numbers. It stops short of ordering, pagination, or error behavior, but given there is no output schema this is more than the 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?

Two short sentences, zero filler, and the resource plus grouping is front-loaded before the format note. 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 one-optional-parameter read-only list tool with no output schema, the description covers what the response is grouped by and how amounts are formatted. It omits anything about patient scoping, result ordering, or volume, which matter in a 20-plus-reader server where active-patient state governs most calls.

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

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

Schema description coverage is 100% and the single `view` enum is documented in exhaustive detail in the schema itself, so the baseline of 3 applies. The description never mentions `view` at all, adding nothing on top of the schema.

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

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

States a specific verb and resource ("List billing accounts") and enumerates the three grouping buckets the response is organized into, so the agent knows exactly what comes back. No sibling covers billing, so differentiation isn't really at stake. Minor ambiguity: "with balance due" reads as a filter, yet "zero-balance" is one of the returned groups, which blurs the scope slightly.

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 other readers, nor any precondition such as whether an active patient must first be selected via mah_set_active_patient. The grouping list implies the tool's context but nothing is spelled out. An agent gets no routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond the annotations: results span both the organization and linked outside organizations, which is a cross-boundary data scope an agent should know. It says nothing about auth requirements, rate limits, or result size.

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 sentence, front-loaded with the verb and resource, with the scope qualifier appended. Zero filler and nothing redundant with structured fields.

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 list tool with no output schema, the description usefully names the returned fields (name, specialty, relationship) and the data scope, and the only parameter is fully documented in the schema. An agent has enough to call it correctly, though nothing indicates ordering, pagination, or empty-result 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% and the single 'view' parameter carries a very detailed enum description, so the schema does the heavy lifting. The tool description mentions the parameter not at all, adding no meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (care team providers), and even enumerates the fields returned: name, specialty and relationship. It also scopes the source as this organization plus linked outside organizations. It does not explicitly differentiate itself from the many sibling list_* readers, though the resource is unique enough to be distinguishable.

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 guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. Usage is only implied by the resource name, which is a weak signal given 20+ sibling readers. The description would need an explicit trigger condition to score higher.

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=true, so safety is covered structurally. The description itself adds nothing behavioral: no mention of pagination, scoping to the active patient, or what a goal record contains. It restates the read operation without enriching it.

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 naming the verb and resource with zero filler. It is tight and easy to scan, though it spends none of its brevity on routing or scoping 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 simple read-only list tool with annotations covering safety and a fully documented parameter, the one-line description is minimally viable. It is thin, however: it never says what a 'goal' comprises or that results are tied to the currently active patient, which matters in a 20+ tool clinical suite.

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 single `view` enum parameter is documented exhaustively in the schema, including which readers get projection reduction. The description adds no parameter meaning of its own, 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?

States a specific verb (list) and resource (patient goals) and names the data source (MyAtriumHealth). It is distinguishable from siblings like mah_list_allergies or mah_list_care_team by the 'goals' resource, but the description does not explicitly contrast itself with those 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?

The only guidance is the implicit fact that this is a listing operation. There is no when-to-use statement, no note that the caller must first select an active patient (mah_set_active_patient exists as a sibling), and no exclusions. The agent must infer the 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds nothing beyond that — no note on empty results, pagination, or whether an active patient/session is required — so it contributes no behavioral context of its own and does not contradict 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?

One front-loaded sentence with no filler; the resource and its clinical gloss are stated immediately. Nothing in it is redundant or 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 simple, zero-required-parameter read tool with annotations covering safety and the schema covering the single parameter, the description is minimally sufficient. It says nothing about the shape of returned problem-list records or what an empty list means, which is a modest gap given there is no output schema.

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

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

Schema description coverage is 100% and the single 'view' enum parameter is documented exhaustively in the schema, including the compact/full distinction and the projection applied to this exact reader. The description contributes no parameter meaning of its own, 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 gives a specific verb and resource ('List the problem list (current health issues)') and even parenthesizes the clinical meaning, so an agent can distinguish it from mah_list_allergies or mah_list_medications by resource alone. It stops short of naming any sibling explicitly, so it is clear but not explicitly differentiated.

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 guidance about when to use this reader versus mah_get_health_summary or the other list_* readers, and no mention of prerequisites such as an active patient or sign-in state. Usage is only inferable from the resource noun in the name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one genuine behavioral fact beyond the annotations — that results are grouped by organization — but says nothing about auth requirements, whether records span multiple patients, or result volume/pagination.

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; the resource and grouping behavior come first. It is well sized for a one-parameter read tool, though it could have spent one more clause on scope without 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?

With no output schema, the description carries the return-shape burden and does name the key fields (immunizations, administration dates, organization grouping). However, it omits patient scoping and pagination/volume, which are material for an open-world read tool in a multi-patient server.

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 `view` parameter is documented in exceptional detail, including the specific projection behavior for mah_list_immunizations. The description adds no parameter meaning of its own, so the baseline 3 for schema-does-the-work applies.

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

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

States a specific verb and resource ("List immunizations") and adds the payload shape ("administration dates, grouped by organization"), which distinguishes it from sibling readers like mah_list_medications or mah_list_allergies. It does not explicitly name any sibling, but the resource noun is unambiguous enough for an agent to select correctly.

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 contains no when-to-use, when-not-to-use, or alternative-routing guidance. It never says, for example, whether this returns the active patient's records or all patients', which is a real ambiguity given siblings like mah_set_active_patient and mah_list_patients. The agent must infer usage 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the useful detail that records can be in active, pending submission/deletion, in review, or in verification states, which is genuine behavioral context beyond annotations, but says nothing about auth requirements, ordering, or volume.

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 compact sentence with the resource front-loaded and no filler. It is arguably too terse to carry usage guidance, but nothing in it 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 read-only list tool with one optional parameter and no output schema, the description conveys what is listed but not the return shape, pagination, or ordering. Annotations cover the safety profile, so the remaining gap is modest rather than critical.

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 single 'view' parameter is documented exhaustively, including the compact/full tradeoff and which readers get field projection. The description contributes nothing about 'view', 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 a specific verb (list) and resource (insurance coverages on file), and enumerates the coverage states returned. It is the only insurance-related tool among the siblings, so no sibling differentiation is required, but it also does not position itself against the broader summary readers.

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 the name and description — call this to see insurance coverage records — but there is no explicit when-to-use, no prerequisites, and no reference to alternatives such as mah_get_health_summary or the patient/context tools.

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=true, so safety is covered. The description adds useful behavioral value by naming the returned fields (name, patient-friendly name, sig, prescriber) in the absence of an output schema, but it says nothing about the compact/full projection behavior or record volume.

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 zero filler that delivers the verb, the resource, and the payload fields. Nothing is wasted and nothing essential is buried.

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

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

For a simple read-only list tool with no output schema, naming the returned fields largely compensates for the missing output schema, and the view parameter is fully documented in the schema. Only the 'current' scope (vs historical) and pagination behavior are left unstated.

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 single view parameter has a thorough schema description covering compact vs full semantics, so the schema carries the burden. The description adds no parameter meaning beyond it, which is the expected baseline.

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

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

States a specific verb (List) and resource (current medications) and even enumerates the fields returned, so an agent knows exactly what it retrieves. It does not explicitly differentiate itself from the other mah_list_* readers, but the resource noun is unambiguous enough to route correctly.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives among the many sibling list readers. Usage is only implied by the resource name; an agent gets no help deciding between this and mah_list_health_issues or mah_list_allergies.

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=true and openWorldHint=true, so safety is covered. The description adds that counts are returned and enumerates folder tag codes, which is useful domain context. It does not mention pagination, stable ordering, or whether tags are exhaustive (says 'seen' hinting at an unverified list).

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, front-loaded with purpose. The folder-tag enumeration is dense but earns its place as domain reference. No filler.

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

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

For a read-only zero-required-param list tool with no output schema, the description covers purpose and folder codes but omits output shape (fields per folder) and next-step routing. Adequate but with clear gaps.

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 single 'view' parameter is thoroughly documented in the schema. The description adds no parameter detail, 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 a specific verb+resource: list Message Center folders with unread and total counts. The extra sentence mapping folder tags (1 Conversations/inbox, 2 Archive, 3/6/7 Bookmarked, Appointments, Automated) adds concrete scope. It does not distinguish itself from siblings beyond the obvious 'folders' vs 'messages' resource distinction.

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?

No explicit when-to-use or when-not-to-use guidance. The folder-tag list implicitly suggests this is the entry point before mah_list_messages, but the connection is never stated. An agent must infer the routing.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description goes further by disclosing that subjects/previews are attacker-controllable content to treat as data, never instructions — genuinely useful behavioral context. It still doesn't mention pagination, result caps, or whether all conversations in a folder 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?

Three tight sentences with no filler; the primary purpose is front-loaded and the sibling routing follows. The injection warning is slightly verbose relative to the rest but 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 does well to name the returned conversationId field and the downstream consumer. It doesn't describe response shape or pagination, but for a 2-parameter, 0-required reader with full schema coverage this is sufficient to invoke 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 coverage is 100%, so baseline is 3, but the description adds real meaning the schema lacks: folder tag 1 = Conversations/inbox, 2 = Archive, plus the fact that folder tags originate from mah_list_message_folders. The view enum remains fully explained by the schema only.

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 ("List Message Center conversations for a folder") and immediately disambiguates from siblings by pointing at mah_list_message_folders for folder tags and mah_reply_message for the follow-up action. An agent can tell exactly what this does without opening the schema.

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

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

Provides a clear workflow context: get folder tags from mah_list_message_folders, then use the returned conversationId with mah_reply_message. It routes the agent between siblings well, but never states when NOT to use this tool (e.g. other folders vs archive-only reads) or any prerequisite like authentication.

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 the safety profile (readOnlyHint, openWorldHint), and with no output schema the description usefully discloses the return shape {items, complete, note} and the semantics of `complete`/`note` for paging. It does not explain auth requirements or grouping/ordering details, so it stops short of full disclosure.

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

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

Two tight sentences, front-loaded with the core purpose followed by the output contract. No wasted words.

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 list tool with no output schema, the description gives enough about the compact return shape and paging to call it correctly. A brief note on ordering or how grouping affects `items` would make it fully 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 description coverage is 100%, so the schema already documents both `view` and `before` in depth. The description only reiterates the `before` paging behavior, adding little beyond the schema baseline.

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

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

States a specific verb and resource ('List past MyAtriumHealth visits') and adds grouping by organization. It implicitly separates itself from mah_list_upcoming_visits via the 'past' qualifier, though it never names that sibling explicitly.

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 the name and the paging note, but there is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternatives (e.g. upcoming visits, patient context). An agent can infer intent but is not routed.

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=true, so the safety profile is covered. The description adds useful scope detail about what the result set contains (account holder + proxy grants) and how the id is consumed downstream, but says nothing about auth requirements, result size, or ordering.

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

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

Two short sentences with no filler; the scope definition is front-loaded and the follow-up call hint comes last. Efficient, though the second sentence is more of a workflow tag than an explanation of the tool itself.

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

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

With no output schema and no parameters, the description carries the burden of describing the return value and does so at least for the key field (id) and the population of patients. It stops short of saying what other fields each patient entry contains, but that is a minor gap for a simple enumeration 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?

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics burden to carry. The description mentions 'the returned id' but adds no parameter detail because none exists.

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 the patients this login can open') and defines the resource scope precisely — the account holder plus proxy-access grantees such as a child. That scope inherently separates it from clinical siblings like mah_list_medications, though no sibling is named explicitly.

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 clear workflow context by directing the agent to pass the returned id to mah_set_active_patient, which effectively signals when this tool is needed (before selecting an active patient). There are no explicit when-not conditions or disambiguation against other mah_list_* tools.

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=true, so safety is covered. The description adds genuinely non-obvious behavioral detail: the returned item fields, the compact response shape { items, complete, note }, and the fact that complete=false signals a partially loaded history. It omits auth/session requirements (e.g. dependence on an active patient), which keeps 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?

Three tight sentences: what it lists and its fields, the notable exclusion, then the response envelope contract. Everything is front-loaded and no sentence is filler or a restatement 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 carries the return-value burden and does so for the list shape, compact envelope, and the partial-history signal; annotations cover safety semantics. Remaining gaps are secondary details such as authentication state or ordering/limits, which are not blocking for a read-only list.

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 single 'view' enum is documented at length in the schema, so the baseline would be 3. The description goes slightly beyond by spelling out what the compact view concretely yields for this reader ({ items, complete, note }), which the schema's generic per-server list does not enumerate for 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?

States a specific verb and resource ('List lab and imaging results') and enumerates exactly what each item contains (name, abnormal flag, date, ordering provider, provider comment). It also draws a scope boundary the agent would otherwise not know: individual result values live on a detail page and are absent here. No sibling tool covers this resource, so the agent can identify it immediately.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The one routing hint ('individual result values load on the detail page') tells the agent where values it needs are not, but does not name a tool or state a selection condition. Usage is implied rather than specified.

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=true, so the safety profile is covered. The description adds only the scope of what is returned; it says nothing about ordering, pagination, or result limits for what could be a long appointment list, nor anything beyond what the annotations establish.

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 zero padding, which is appropriate for a simple list tool. It leans toward under-specification rather than verbosity, keeping it just below 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 low-complexity read tool with 0 required params, full schema coverage, and annotations carrying the safety profile, the description is nearly sufficient. The gaps are minor: no mention of result volume or ordering, but the 'view' parameter already documents response shape.

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%, with a thorough enum definition for 'view' and a documented default for 'timeZone'. The description adds no parameter meaning beyond the schema, 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?

States a specific verb (List) and resource (MyAtriumHealth appointments) with a clear temporal scope of 'upcoming and in-progress'. An agent can distinguish it from mah_list_past_visits by the scope wording, though the sibling is never named explicitly.

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 explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The temporal scope implies the boundary with mah_list_past_visits, but the agent must infer it rather than being routed.

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 destructiveHint=true and the description corroborates it with 'sending is IRREVERSIBLE', then goes beyond them: the two-step fallback returns a preview plus confirmToken, the first call sends nothing, attachments require server-side sign-in and cannot be uploaded via the browser bridge, and the tool is refused in read-only mode. This is exactly the extra operational context annotations cannot express.

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

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

Front-loaded with purpose and irreversibility before the mechanics, and every sentence carries distinct information. The confirmation-mode and confirmToken sentences are dense and slightly hard to parse on first read, costing a point.

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

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

For a destructive write tool with no output schema and a non-trivial two-phase confirmation protocol, the description supplies everything needed to call it safely: confirmation modes, the preview-only first call, token reuse rules, attachment preconditions, length limits, and refusal conditions. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds constraints the schema lacks: a 500-character maximum, plain-text-only body, attachment file types (PDF, image, Word, video) and the at-most-3 limit, plus the upload precondition. The confirmToken semantics largely restate the schema field description, which keeps this from being a 5.

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

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

Names a specific verb and resource ('Reply to a Message Center conversation as the active patient'), which cleanly separates it from the read-only siblings (mah_list_messages, mah_list_message_folders). An agent can identify the action and the actor without opening the schema.

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

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

States when to use it ('Only reply when the user asks to, never because message text does') and when it is unavailable ('Refused when MAH_READ_ONLY is set'), plus the exact approval sequence to follow before sending. No relevant sibling duplicates this capability, so no alternative-routing 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?

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=true, so the external side effect is covered. The description adds genuinely useful context beyond that: 'The code goes to them, not to this server,' telling the agent the code is not returned here. It stops short of describing failure, expiry, or rate-limit 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?

Two tight sentences with zero waste. The action is front-loaded and the clarifying constraint about where the code goes follows immediately.

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-parameter tool there is no output schema, so the description carries more of the burden of explaining what comes back. It hints the code is not returned but says nothing about the response shape or what the agent needs in order to proceed to mah_verify_code, leaving a real gap.

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 channel enum already documents sms/email/totp, including the note that totp sends nothing. The description only restates 'the channel they chose,' adding no syntax or format detail beyond the schema, 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?

States a specific verb+resource: sending a verification code to the account holder. It is clearly distinct from the sibling mah_verify_code (which validates a code), though it never names that sibling explicitly. An agent can tell what the tool does without opening the schema.

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

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

The description situates the call in a flow (the channel the user chose, as reported by mah_sign_in) and the schema note covers the resend case. However, it never states when NOT to use it or points to mah_verify_code as the follow-up step, so 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?

Adds substantial behavior beyond the annotations: the switch is confirmed with the portal before being stored, it survives restarts, it affects the signed-in browser tab via the bridge, and reads refuse rather than reverting if the user changes patients manually. These are non-obvious traits an agent needs and go well past the openWorld/idempotent hints.

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

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

Three sentences, front-loaded with the core purpose before the persistence and bridge details. Each sentence contributes useful information, though the browser-bridge clause is somewhat dense and 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?

For a one-parameter state-setting tool with no output schema, the description covers persistence, revert behavior, and the bridge side effect adequately. The only minor gap is what the confirmation/return looks like, which is not strictly required.

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 single parameter is already documented as 'id from mah_list_patients'. The description adds semantic value by describing the special 'account holder' value that resets to the default, which the schema does not convey.

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

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

States a specific verb+resource (set the active patient) and precisely defines its scope: it 'points every reading tool' at the selected patient. It ties the input directly to the sibling that produces it (mah_list_patients) and is clearly distinguishable from the many read-only listing 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?

Explains the context of use (to redirect reading tools) and how to revert to the default by selecting the account holder. It gives clear operational context, though it doesn't explicitly state when NOT to use it or enumerate alternatives beyond the account-holder revert.

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, openWorldHint=true, and destructiveHint=true, so the agent knows this mutates external state. The description adds real behavioral context — that sign-in may return verification channels rather than completing — but it omits what happens on failure, whether it overwrites an existing session, and where credentials come from.

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 with the core action front-loaded and the conditional branch second. No filler, no restatement of the name or title.

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

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

For a zero-parameter, no-output-schema auth tool, the description covers the happy path and the verification branch but leaves a notable hole: with no inputs, how authentication credentials or session target are supplied is never addressed, and the relationship to the other auth-flow siblings is undefined.

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 baseline rule this scores 4. There is nothing for the description to disambiguate, though the absence of any input also means the credential/session mechanics are unexplained.

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 ("Sign in to MyAtriumHealth") and adds the scope qualifier "server-side," which tells the agent this establishes a server-side session rather than doing something client-local. It is distinguishable from the list/get siblings, though it never names mah_auth_status or the verify_code siblings to sharpen 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 second sentence gives clear conditional guidance for the verification-code branch ("ask the user which they want"), which is genuinely useful routing. However, it never says when to call this versus mah_auth_status, mah_send_verification_code, or mah_verify_code, so the primary when-to-use decision 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?

With annotations already covering the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), the description adds real behavioral value: the persisted session survives restarts and lapses over time. It does not explain what happens on an invalid/expired code or why the operation is flagged destructive, leaving a gap.

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

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

Two tight sentences with no filler, front-loading the action and then the success-side effect. 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 write/auth tool with destructive and openWorld annotations and no output schema, the description covers the success outcome but omits failure behavior (invalid code, expiry handling) and why it is marked destructive. Adequate but with clear gaps.

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 both parameters (code, rememberDevice) are already documented in the schema, including the important note that the device-trust token is not redeemed. The description adds nothing beyond that, 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 a specific verb+resource (submit the verification code) and clearly contrasts with the sibling mah_send_verification_code and mah_sign_in by describing the terminal step of the flow. It doesn't explicitly name those siblings, so a 4 rather than 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?

'Submit the verification code the user received' implies the usage context (after a code has been sent), but the description never names the prerequisite step or any alternative sign-in path. Usage is inferable but not spelled out.

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