mediora-mcp

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

Goes well past annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) by disclosing the async non-terminal response, the SSRF-style URL restrictions (no localhost, cloud-metadata, private LAN), no redirect following, and the 10 MB / MIME limits. These are exactly the failure modes an agent would otherwise hit blindly.

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

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

Four short sentences, front-loaded with purpose and return contract, then constraints. Every clause carries operational information; nothing is redundant with the schema or annotations.

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

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

For a mutation-flavoured ingestion tool with no output schema, the description covers the async return, the size/MIME/network acceptance criteria, and points at mediora__whoami (via schema) for the token. An agent can call it and handle the result without further guessing.

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 real semantics beyond the schema's 'Public HTTPS URL' by specifying scheme, reachability, size and MIME constraints, plus redirect behaviour. It adds nothing about bearer_token or language, which the schema already documents.

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 (upload + trigger analysis) on a specific resource (lab-report PDF/scan) and names the async contract: it returns a pending test id the client can poll. No sibling in the list performs ingestion, so it is unambiguous against explain_*/list_*/get_test_details.

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?

Describes the invocation context (HTTPS URL, public-IP reachable, PDF/JPEG/PNG ≤10MB, no redirects) and implies the follow-up action of polling the returned test id. It never names the polling sibling (get_test_details) or states when not to use this tool, 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 establish that this is read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral detail by enumerating what the explainer includes, which is valuable because there is no output schema. It does not describe not-found behavior, but the annotation coverage lowers the bar.

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 action and followed by the returned content. There is no filler or redundancy.

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

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

For a simple read-only lookup with a fully described two-parameter schema, the description covers the purpose and the returned content well enough. The main gaps are not-found behavior and explicit sibling differentiation, which are minor but real.

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 the slug and lang parameters are already documented. The description adds only that the lookup is 'by slug' and that the result is a full explainer; it does not add syntax, format, or semantic detail 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: returns the full explainer for a clinical condition by slug. The resource is clear enough to separate it from explain_marker, explain_panel, and explain_symptom, but it does not explicitly name those siblings or clarify the boundary.

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

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

The description implies the tool is used when an agent has a condition slug and needs the explainer, but it gives no explicit when-to-use guidance, no when-not-to-use guidance, and no alternatives. The schema mentions list_conditions for slug discovery, but that guidance is not in the description itself.

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 cover read-only/idempotent/non-destructive, so the description wisely spends its words on output semantics: action fields are intentionally empty when the value follows an underlying cause ('which is itself the answer'), and rangeSource carries title/url/checkedOn. That prevents an agent from misreading empty fields as a failure. It stops short of indicating size/length or completeness guarantees of the explainer.

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 in the first clause, and the follow-on detail about action fields and rangeSource is directly useful. The two sentences are dense with em-dash digressions, but no sentence is pure 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 must carry the return-value burden, and it does describe the conceptual sections returned plus the meaning of empty action fields and the rangeSource object. It omits actual field names/shape the agent might need to render results, and does not explain lang behavior, but the essential behavior is covered.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the discovery path for slugs and the lang default. The description only restates 'by slug' and never mentions the lang parameter or whether the explainer text is localized, so it adds minimal value over the schema.

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

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

The description gives a specific verb+resource ('Return the full explainer for a single blood-test marker by slug') and enumerates the payload (what it measures, high/low meaning, actionability, conditions, actions). It does not, however, differentiate itself from the close sibling 'lookup_marker' or from explain_condition/explain_panel, leaving the agent to infer the split between 'explain' and 'lookup'.

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

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

Usage is only implied by the word 'explainer'; there is no explicit statement of when to prefer this over lookup_marker or list_markers. The only routing hint (use list_markers to discover slugs) lives in the schema, not the description, and no when-not conditions are given.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the burden is light. The description still adds useful substance: the response is a shallow projection (slug + name + one-line summary, not full marker detail), and it discloses the alias field that the schema doesn't mention. No return shape or edge-case (unknown slug) behavior is stated, keeping it below 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 tightly packed sentences, front-loaded with the return contract, then the user question it answers, then the follow-up route. The alias parenthetical is dense but earns its place as illustrative input examples.

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

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

There is no output schema, and the description compensates by enumerating the returned fields and the alias list. Combined with the schema's own slug-discovery pointer to mediora__list_panels, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so a 3 is the floor. The description goes beyond it by making explicit what the slug resolves to and that names/summaries are the localized payload, which implicitly explains the purpose of the 'lang' parameter; concrete panel-slug examples reinforce the expected format.

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 ('Return the markers that make up a lab panel by slug') and names what is returned (marker slug, name, one-line summary, plus panel aliases). It is clearly distinct from sibling mediora__explain_marker, which it explicitly positions as the deeper-detail tool.

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

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

Gives a concrete triggering question ('what's included in a CBC / lipid panel / CMP') and routes the agent onward to mediora__explain_marker for full detail. It does not state an explicit when-not-to-use or point to mediora__list_panels for slug discovery in the description (that lives in the schema), so it falls just short of full coverage.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing the returned content (meaning, causes, lab work-up, urgent-evaluation criteria) and the side-car slug arrays that enable graph traversal. Missing: behavior for an unknown slug or translation fallback.

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: the action and scope come first, then the payload contents and the graph-following hint. No filler and no repetition of the 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?

With no output schema, the description usefully enumerates the explainer's sections, which is exactly the burden it must carry. For a two-parameter read tool that is close to sufficient; only error/edge behavior (unknown slug, language fallback) is 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%, so both slug and the lang enum are already documented, including slug discovery guidance. The description only restates 'by slug' and adds no format or normalization detail beyond the schema. There is a minor inconsistency worth noting: the schema points to list_markers/list_conditions for slug discovery, while this is a symptom tool (list_symptoms 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: 'Return the full triage explainer for a single symptom by slug', and enumerates the sections returned. It is clearly a per-symptom detail lookup, distinct from the list_* siblings, though it never names the alternative tools by contrast (only as downstream graph hops).

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 'for a single symptom by slug', and the second sentence gives forward guidance on following related marker/condition arrays into mediora__explain_marker / explain_condition. There is no explicit statement of when to use this instead of mediora__list_symptoms or lookup_marker, and no prerequisites or exclusions.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds real value beyond them: the patient-scope token requirement, default page size of 10, and the fact that it proxies https://api.mediora.ai/api/medical-tests with the token forwarded.

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

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

Three tight sentences, front-loaded with the returned payload then auth, then pagination/upstream details; 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?

No output schema exists, so listing the row fields is valuable and covers the return shape; auth and pagination are covered too. Only gaps are error/permission-failure behavior and empty-history behavior.

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

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

Schema coverage is 100% and the schema already documents page, page_size (default 10, max 50) and the bearer_token; the description restates the page-size default and adds the token's required scope, but nothing beyond that. Baseline 3 applies.

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

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

States a specific verb and resource ('Return the patient's past medical-test rows') and enumerates the returned fields, which distinguishes it from the singular mediora__get_test_details and from mediora__longitudinal_trend.

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 context (patient-scope JWT required, pagination defaults) but does not say when to use this list versus mediora__get_test_details or mediora__longitudinal_trend, nor any exclusions.

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

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

Beyond the annotations (readOnly/idempotent/non-destructive), the description discloses ownership scoping (the patient must own the test), the token scope required, and the fact that the call proxies https://api.mediora.ai/api/medical-tests/{id} with the user's bearer token forwarded. That tells the agent where data comes from and why auth failures are likely, which is exactly the context annotations cannot 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?

Three sentences, front-loaded with the payload and its four fields, then the sequencing hint, then the auth/proxy mechanics. No filler and no restatement of the 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?

No output schema exists, and the description compensates by naming the returned sections (Summary, KeyFindings, Recommendations, DetailedExplanation). Combined with the auth mechanics and id provenance, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds the provenance of test_id (an `id` from patient history) and sharpens the token requirement to a patient-scope JWT forwarded as Authorization: Bearer. That goes slightly beyond the schema's generic "Mediora.AI patient JWT" wording.

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

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

Specific verb (Return) plus a precisely enumerated resource (persisted markers + AI analysis with the four named sections) scoped to a medical-test the authenticated patient owns. It is clearly distinguishable from mediora__get_patient_history, which surfaces the ids rather than the detail payload.

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

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

"Use after mediora__get_patient_history surfaces a test id the user wants to discuss" gives an explicit trigger condition and names the sibling that produces the required input. It also states the auth prerequisite (patient-scope JWT), so the agent knows both when and how to be eligible to call 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds value by stating the returned fields (slug, name, ICD-10 code) and that the list is exhaustive ('every'), implying no pagination. It does not discuss ordering or the language parameter's effect on labels.

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

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

Three short sentences, zero filler, with the resource scope front-loaded and the return shape and alternative following in priority order.

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 read-only list tool with no output schema, the description supplies the return fields and the sibling routing the agent needs. Ordering and language fallback behavior are the only minor unspecified details.

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 optional 'lang' parameter is documented with an enum in the schema itself. The description adds no semantics 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 and resource ('List every clinical condition in the Mediora catalog') and immediately declares the return fields. It is clearly distinguishable from the explain_* and list_* siblings 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?

The final sentence explicitly routes the agent to mediora__explain_condition when a full explainer is needed, which is the main sibling overlap. There are no explicit exclusions beyond that, but the catalog-vs-detail split is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new information by naming the return shape ('slug + short name per entry'), which matters because there is no output schema.

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

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

Two short sentences, the scope statement first and the alternative second; every clause carries information 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?

For a trivial enumeration tool with full annotation coverage, the description supplies the missing return shape and points at the natural next call. Ordering, entry count, or whether markers are grouped by panel are unstated but not 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?

With one optional parameter at 100% schema coverage and an enum plus default documented in the schema, the schema does the heavy lifting. The description never mentions the lang parameter or what happens when a translation is missing, so it adds nothing beyond structured data.

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

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

States a specific verb and resource ('List every blood-test marker in the Mediora catalog') and pins the scope to the whole catalog, which separates it from lookup_marker and the explain_* siblings. An agent knows exactly what it gets without opening the schema.

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

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

Explicitly routes to mediora__explain_marker when the agent needs the full explainer, which is the most likely follow-up. It doesn't address lookup_marker or list_panels, so the discovery-vs-lookup boundary is left implicit, keeping this just short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the description adds value by disclosing the return shape (slug, name, marker count). It stops short of noting result size or whether the list is static/paginated, but that's a minor gap for a small fixed catalog.

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

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

Two sentences, front-loaded with the core action, then the routing hint. The long parenthetical enumeration of panel types is slightly bulky but communicates catalog coverage and is the most informative part of the description.

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 supplies the return fields and the sibling pointer, which is everything an agent needs to call a zero-arg list tool 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?

The tool takes no parameters, so there is nothing to disambiguate; baseline is 4. The description correctly avoids inventing filtering options.

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 (lab panels in the Mediora catalog), enumerates representative panel types, and specifies the return payload (slug + name + marker count). It also distinguishes itself from mediora__explain_panel by name.

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

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

Explicitly routes marker-level lookups to mediora__explain_panel, making the boundary between the two tools clear. It doesn't state preconditions or when-not to call it, but for a zero-arg catalog listing that context is mostly implicit.

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, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing the return shape (slug + short name) and the fact that this is a bounded catalog enumeration rather than a filtered query. It does not mention language behavior, which is the one remaining behavioral gap.

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

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

Two sentences, both earning their place: the first defines scope and return shape, the second routes to the correct sibling. The core purpose is front-loaded with zero preamble.

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 one-parameter catalog lister with no output schema, the description supplies everything required: what is listed, what comes back, and when to prefer the richer sibling. Annotations cover the safety profile and the schema covers the language option, so no material gap remains.

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 lang parameter is fully documented with an enum, so the schema does the heavy lifting and a 3 is the baseline. The description never mentions that output is language-selectable, adding no meaning over the schema, though nothing is misleading.

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 plus resource ("List every patient-side symptom in the Mediora catalog") and grounds it with concrete examples (fatigue, joint pain, headache). It explicitly distinguishes itself from the sibling mediora__explain_symptom, so an agent can choose between the two without opening a schema.

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

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

Names the alternative tool explicitly (mediora__explain_symptom) and states the condition that selects it: when the agent needs the full triage-oriented explainer with lab work-up. The implicit inverse — use this tool for a plain enumeration — is also clear from the first sentence.

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 it read-only, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: it discloses the authentication mechanism (user's bearer token forwarded upstream) and enumerates the response fields (marker slug, kind, severity, trend/year, sample count, date range, headline, detail). Only error/pagination behavior is left unstated.

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

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

Front-loaded with the purpose, then the response shape, then the proxy/auth detail — a logical order. The field enumeration is long but justified because there is no output schema; no sentence is filler, though the sentence count could be trimmed slightly with list formatting.

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 by listing the key fields; auth requirements are disclosed and the upstream endpoint is named. Minor gaps are absence of empty-result behavior and upstream error handling, but nothing an agent needs to invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so the single bearer_token parameter is already fully documented, including how to obtain it. The description still adds meaning by explaining what the tool does with the token — forwards it as 'Authorization: Bearer' to the upstream trajectory endpoint — which the schema alone does not say.

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 ('Return the per-marker trajectory analyser output') with scope ('authenticated patient') and concrete examples (HbA1c rising, eGFR falling, ferritin depleting). This clearly distinguishes it from siblings like explain_marker, lookup_marker and get_patient_history, which explain a marker or fetch history rather than computing per-marker trends.

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 usage context is only implied — it is for the authenticated patient and proxies a specific trajectory endpoint — but there is no explicit 'use this when...' or exclusion against get_patient_history or explain_marker. An agent can infer it yields trend warnings, but has to reason about the alternative itself.

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/idempotentHint, so those add nothing. The description contributes real behavioral context beyond them: matching is fuzzy over aliases across three languages, and the result is a canonical slug rather than a full record. It doesn't say how many matches come back or how ties are ranked, keeping it off a 5.

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

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

Two sentences, no filler. The core action and language scope come first, and the motivating use case follows as supporting context.

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 lookup with no output schema, the description covers purpose, input expectations, and the shape of the return (a slug). It omits what happens on multiple or zero matches, a minor but real gap for a fuzzy-search 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%, so baseline is 3. The description adds meaningful semantics the schema doesn't: `query` is matched fuzzily against aliases, not exact names, so partial and transliterated inputs are acceptable. `lang` handling is left entirely to the schema.

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

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

States a specific verb and resource ('fuzzy-search markers by alias'), scopes it to EN/RU/HE, and implies the output ('canonical Mediora slug'), which separates it cleanly from explain_marker and list_markers.

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

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

Gives a concrete triggering condition: the caller has a lab-local name rather than a canonical slug, with examples in three scripts. It does not explicitly name an alternative tool or state when not to use it, so it falls short of the top band.

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/idempotentHint/non-destructive, so the safety profile is covered; the description adds that it returns patient id + email and where the JWT comes from (login at mediora.ai, localStorage 'auth_token'). It does not disclose what happens on an invalid or expired token (error vs empty result), which matters for a validation 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?

Two sentences, zero filler, with the purpose and the 'use first' directive front-loaded before the token-origin detail.

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

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

With no output schema, the description correctly names the return values (patient id + email) and the token source. The one missing piece is failure behavior for an invalid/expired token, which an auth-gate tool should state.

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 goes slightly beyond by reiterating the token's origin and tying it to the browser's 'auth_token' key, reinforcing how to obtain the one required parameter.

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 ('Validate a Mediora.AI patient Bearer token') plus the return payload ('patient id + email'), which no sibling tool does. It is clearly distinguishable from the lookup/explain tools in the sibling list.

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

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

Explicitly says 'Use this first to confirm the token before calling other auth-gated tools', giving both ordering and the condition that selects it. It also points to the login flow that produces the token, so an agent knows the prerequisite.

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