FinchNode Synthetic Health Records

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: no authentication needed, data is fixed/fictional sample EMR, and data is normalized from FHIR R4 AllergyIntolerance. It does not contradict annotations.

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

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

The description is two sentences with no wasted words. It front-loads the primary purpose, then provides the alternative usage and authentication context. Every sentence contributes useful 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 zero-parameter tool with an output schema and comprehensive annotations, the description covers usage, alternatives, data source, and authentication. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool has zero parameters, so baseline is 4. The description's note about 'only allergies' clarifies the tool's fixed scope, but there is no parameter-specific semantics to add. This is adequate.

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

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

The description clearly states it returns 'only the allergies of FinchNode's fixed fictional sample EMR' and explicitly differentiates itself from get_demo_health_record. It names a specific resource and is unambiguous about scope.

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 provides both a positive use case ('get only the allergies') and an explicit alternative when broader data is needed ('call get_demo_health_record once instead'). It also notes no account or API key is required, helping an agent decide when to invoke 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, and closed-world behavior. The description adds valuable context beyond annotations: no account or API key is required, and the data is a fixed fictional sample EMR normalized from FHIR R4 Condition. No contradiction exists.

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

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

Three concise sentences with no wasted words. The primary purpose is front-loaded, the data source and format are specified, and the alternative tool is mentioned only where useful.

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 tool with rich annotations and an output schema, the description provides everything an agent needs: scope, data source, normalization standard, auth expectations, and routing instructions. Nothing important is missing.

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

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

The input schema has zero parameters and 100% schema description coverage, so the baseline is 4. The description does not need to document parameter semantics because there are none to document.

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

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

The description clearly states the specific verb and resource: getting only the conditions from FinchNode's fixed fictional sample EMR. It identifies the data as FHIR R4 Condition and distinguishes itself from sibling tools by explicitly limiting scope to conditions only.

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

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

It explicitly tells the agent when to use this tool (when only conditions are needed) and names the alternative (get_demo_health_record) for retrieving conditions together with other categories. This directly differentiates it from siblings and prevents over-calling.

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 readOnly/idempotent annotations, the description reveals that the data is synthetic and from a fixed fictional sample EMR, and that no account or API key is required. These are meaningful behavioral and access context that annotations do not provide.

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

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

Two sentences, front-loaded with the exact purpose and field list, followed by a clear alternative. 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?

With no parameters, a rich output schema, and annotations covering safety, the description supplies the remaining essentials: data source, synthetic nature, auth requirements, and sibling routing. An agent has everything needed to invoke it correctly.

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

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

The tool has zero parameters, so the schema already fully covers parameter needs. The description adds value by listing what fields the returned demographics include, which helps set expectations even though no parameters exist.

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

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

The description clearly specifies the verb 'get' and resource 'basic details (demographics)', enumerates the exact fields (name, birth date, sex, contact information), and states it is normalized from FHIR R4 Patient. It also distinguishes this tool from the broader get_demo_health_record sibling.

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

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

It explicitly says to use this tool when only basic details/demographics are neededcars. It also gives a direct alternative: call get_demo_health_record once to get basic details together with other categories, preventing unnecessary multi-tool calls.

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 readOnly, idempotent, non-destructive, and closed-world hints. The description adds useful behavioral context beyond that: the data is a fixed fictional sample, no authentication is needed, and the content spans encounters, appointments, and care teams normalized from FHIR R4. This meaningfully supplements the structured hints without contradiction.

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

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

The description is compact and well-structured. It opens with the primary purpose, adds important data-source and authentication context, and closes with a clear routing instruction to a sibling tool. No sentence 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 parameterless read-only tool with a rich output schema and strong annotations, the description covers everything an agent needs: what data is included, its source, the fact that no auth is needed, and when to choose an alternative tool. Nothing critical is missing.

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

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

The tool has zero parameters, so the description has no parameter semantics to explain. The schema is empty and the description provides all necessary context about what the tool returns, satisfying the baseline for parameterless tools.

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

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

The description clearly states the tool's function: getting only visits/encounters from FinchNode's fixed fictional sample EMR. It distinguishes itself from get_demo_health_record by explicitly noting it returns only visits, and clarifies the data is normalized from FHIR R4 Encounter, Appointment, and CareTeam.

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 explicitly says to use this tool when you want only visits, and names get_demo_health_record as the alternative when visits are needed alongside other categories. It also notes that no account or API key is required, giving clear and actionable usage context.

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, idempotentHint=true, and destructiveHint=false, covering safety and mutation behavior. The description adds no extra behavioral context beyond stating it returns a bundle (which is purpose). Given the annotations, the description adequately covers the safety profile, so a 3 is appropriate for no added behavioral nuance.

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

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

The description is a single, focused sentence that front-loads the key usage context and the primary output. There is no unnecessary information, and every word contributes to clarity.

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?

Given the tool has no parameters, an output schema, and simple purpose, the description fully covers what an agent needs: what the tool returns (complete bundle) and when to use it. There are no missing details like error handling or formatting that would be essential for correct invocation.

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

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

The tool has zero parameters, and the schema coverage is trivially 100% (no properties). Per the rubric, a baseline of 4 is given for zero parameters. The description doesn't need to explain parameters, and it doesn't.

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

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

The description clearly states the tool returns the complete fictional FinchNode FHIR R4 Bundle and its resource references, and places it in the context of prototypes/tests. This distinguishes it from sibling tools that return specific resource types (allergies, conditions, etc.), making the purpose unambiguous.

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

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

The description explicitly states when to use the tool ('when a prototype or test needs the complete...Bundle'), which implies that for individual resources the sibling tools should be used. It doesn't explicitly name alternatives or provide exclusions, but the contrast with sibling names is clear enough.

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 flag read-only, idempotent, non-destructive, closed-world behavior, and the description adds meaningful context on top: the data is normalized to schemaVersion 2, patient is fixed/fictional, consent and sync are simulated, and empty categories are a fixture artifact rather than meaningful absence. No contradictions.

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

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

The description is front-loaded with the primary purpose and the preference over single-category tools, then adds necessary caveats. The only slightly dense phrase is the schemaVersion 2 data-shape note, but it is relevant and not wasteful.

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 tool with an output schema and read-only/idempotent annotations, the description provides enough context: what it returns in general, its normalized shape, and its demo-only limitations. It could be more complete by naming the alternative tools it is not (get_demo_record, search_demo_fhir).

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 0% schema description coverage, the description must compensate. Listing the category mix and saying they can be combined in one call helps, but it omits 'documents' and 'claims' from the schema's enum and doesn't explain behavior when categories is absent or empty. It is adequate but has clear gaps.

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

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

The description opens with a specific verb and resource: fetching a platform-shaped synthetic health record with 'any mix' of eight listed categories in one call. It explicitly routes the agent away from 'several single-category tools,' but it never distinguishes this tool from the sibling get_demo_record or search_demo_fhir, so sibling differentiation is incomplete.

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

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

It gives an explicit usage preference: choose this over using multiple single-category tools when a mix is needed. It also sets important constraints (fixed fictional patient, simulated consent/sync, no usable receipts or change cursor), though it does not enumerate exclusions or when to use get_demo_record/search_demo_fhir.

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, and non-destructive behavior. The description adds valuable context beyond that: the data is FinchNode's fixed fictional sample, no account or API key is needed, and the data is normalized from FHIR R4 Immunization. This is meaningful behavioral context without contradicting 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?

Three sentences, each earning its place: the first states the core purpose, the second adds data-source and auth context, and the third gives routing guidance to an alternative. Information is front-loaded and there is 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?

With zero parameters, a read-only annotation set, and an output schema present, the description covers all necessary operational context: what data to expect, that no credentials are needed, and how to get a broader dataset. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool has zero parameters and the schema covers 100% of them trivially, so the baseline is 4. There is nothing for the description to add about parameters, and it correctly does not invent any.

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

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

The description states a specific verb ('get') and resource ('immunizations'), and narrows scope with 'only' and 'Vaccination history, normalized from FHIR R4 Immunization.' It also signals how this tool differs from the sibling get_demo_* tools by directing combined requests to get_demo_health_record.

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

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

It explicitly says when to use this tool (to get only immunizations from the sample EMR) and when not to (when immunizations are needed alongside other categories, call get_demo_health_record once). It even warns against calling several tools unnecessarily, which is direct usage 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context: there is 'No account or API key', the data is a 'fixed fictional sample EMR', and results are normalized from FHIR R4. This goes beyond the structured annotations without contradicting them.

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

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

The description is three sentences with no filler. It front-loads the core purpose, adds the data source detail, and then gives the alternative tool guidance. Every sentence earns its place.

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

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

For a zero-parameter, read-only tool with a rich annotation set and an output schema, the description covers what an agent needs to select and invoke it correctly. It states the scope, the synthetic nature, the lack of auth requirements, and how to get broader results, leaving no critical 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?

The input schema has zero parameters and 100% coverage, so there is no parameter detail for the description to add. The baseline of 4 applies, and the description contributes relevant access context by noting no account or API key is required.

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

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

The description uses a specific verb and resource: 'get only the lab results (labs)' of FinchNode's fixed fictional sample EMR. It also names the data source and normalization standard (FHIR R4 Observation, DiagnosticReport), making the tool's purpose unambiguous. It further distinguishes itself by explicitly noting it returns only labs, not other categories.

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 explicitly states when to use this tool: when only lab results are needed. It also gives a clear alternative and condition: 'To get lab results together with other categories, call get_demo_health_record once instead of calling several of these tools.' This provides actionable routing guidance beyond simple purpose.

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, and destructiveHint, so the safety profile is covered. The description adds valuable behavior context: no account or API key is required, and the data is synthetic, fixed, and normalized from FHIR R4 resources. This goes beyond the structured annotations without contradicting them.

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

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

The description is three concise sentences, front-loaded with the primary purpose, followed by useful auth context and an alternative tool. Every sentence earns its place and nothing is redundant.

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

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

For a zero-parameter, read-only tool with an output schema and rich annotations, the description is complete. It explains what data is returned, that no credentials are needed, and how to combine categories via an alternative 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 input schema has zero parameters, so the baseline for parameter semantics is 4. The description adds no parameter-specific meaning, but none is needed; the tool takes no inputs. The description's scope clarification is sufficient.

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: getting only the medications from FinchNode's fictional sample EMR. It also specifies content (active and past prescriptions) and the FHIR R4 sources, distinguishing it clearly from sibling tools that provide other categories.

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

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

It explicitly says when to use this tool ('to get only the medications') and gives a direct alternative: call get_demo_health_record once instead when medications are needed alongside other categories. This gives an agent clear routing guidance without needing to inspect siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context beyond them: the response is a legacy FHIR shape, the tool is a compatibility shim for prototypes, and the patient is always the same fixed fictional person. It does not detail behavior when categories are omitted, but the output schema covers the response shape.

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

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

Four short sentences, each earning its place: the legacy format, prototype compatibility, the direct alternative, and the fixed-patient constraint. The most identifying attribute is front-loaded, and there is 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?

With one optional parameter, strong annotations, and an output schema, the description is complete enough to call the tool correctly and choose between it and the primary sibling. The category-specific sibling tools are not referenced, but the schema and named alternative make the tool's behavior clear.

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%: the only parameter, categories, is fully described in the schema as an 'Optional subset of normalized record categories.' The description itself adds no parameter-level semantics, so the baseline of 3 applies.

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

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

The description clearly identifies a get-operation for a synthetic health record in a legacy categorized FHIR format, and explicitly contrasts it with get_demo_health_record for normalized data. 'Fixed fictional patient only' further scopes the tool, making it distinguishable from all sibling record retrieval tools.

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

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

'For normalized platform-shaped data, use get_demo_health_record' is an explicit condition-plus-alternative. 'Kept compatible for existing prototypes' tells the agent when the legacy path is appropriate, and 'Fixed fictional patient only' makes an important exclusion explicit.

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, and destructiveHint, so safety is covered. The description adds valuable context beyond annotations: it is a fixed fictional sample EMR, requires no account or API key, and returns data normalized from FHIR R4 Observation. This gives the agent an accurate behavioral model without contradicting 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?

Three tightly written sentences, with the core purpose front-loaded and no filler. Every sentence adds distinct value: what is returned, the auth/sample context, and the sibling alternative.

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 read-only tool with an output schema and comprehensive annotations, the description covers purpose, scope, data source, authentication, and routing to the appropriate sibling. Nothing needed for correct invocation is missing.

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

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

The tool has zero parameters, so there is nothing for the description to explain beyond the data scope, which it does by listing vital sign categories. Per the baseline for zero-parameter tools, this is sufficient.

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

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

The description names a specific verb ('get'), a specific resource ('vital signs'), and enumerates the measures (blood pressure, heart rate, weight). It also explicitly contrasts itself with get_demo_health_record, so an agent can distinguish this tool from its siblings 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?

It states when to use this tool ('only the vital signs') and explicitly directs the agent to call get_demo_health_record when vitals are needed alongside other categories, preventing unnecessary multiple calls. This is clear usage guidance with a named alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by noting the fixed fictional sample and that all resources of a single FHIR type are returned, but it does not mention pagination, rate limits, or any quirks beyond that. There is no contradiction with annotations.

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

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

One sentence, front-loaded with 'Use this to', no filler. It earns its place by naming the action, object, and source in a single pass.

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

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

The tool is low-complexity (one required enum param, one optional fixed param) and has an output schema plus strong annotations. The description, schema, and annotations together tell an agent what to pass and what to expect, so no additional explanation is required for correct invocation.

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

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

The schema covers all parameters with descriptions, including the enum of FHIR resource types and the optional fixed patient filter, so the description does not need to repeat them. It adds no new parameter-level detail, but at 100% schema coverage the baseline score of 3 is appropriate.

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

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

The description names a specific action ('get all resources'), a precise target ('one FHIR R4 type'), and the data source ('FinchNode's fixed fictional sample EMR'). This makes it easy to tell apart from the sibling get_demo_* tools, which are organized by clinical category rather than by FHIR type.

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

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

The opening 'Use this to' gives a clear purpose: retrieve all resources of one FHIR R4 type, which signals when this general search tool is appropriate. It does not explicitly mention sibling alternatives or state when not to use it, but the intended context is unambiguous and no exclusions are needed given the fixed demo scope.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds value by specifying 'non-persistent, immediately complete synthetic session', which clarifies side effects and the nature of the output. This extra context goes beyond the annotations without contradicting them.

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 zero filler. The purpose is front-loaded, and the second sentence adds key behavior details (non-persistent, synthetic) without redundancy. Every word 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 two-optional-parameter tool with a clear output schema and annotations, the description is adequate. It conveys the essential purpose and behavior. It does not explicitly draw the contrast with the record-retrieval siblings, but the purpose statement is sufficient given the structure. A slightly more explicit usage note would make it a 5.

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

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

Both parameters are already fully described in the schema (categories enum and external_user_id pattern, maxLength, and explicit guidance to not use real patient identifiers). The description adds no parameter-specific insight, so it remains at the baseline of 3 given 100% schema description coverage.

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

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

States a specific purpose: 'Use this to prototype the FinchNode connection journey.' This clearly distinguishes it from sibling get_demo_* tools, which retrieve specific record categories. The verb 'prototype' and resource 'connection journey' are precise and non-tautological.

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

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

The description frames it as 'Use this to prototype...', implying it is for the connection journey rather than for retrieving records, but it does not explicitly compare to alternatives or state when not to use it. Given the sibling set of get_demo_* tools, the usage is implied but not articulated.

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