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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the log records every PHI read/write, which adds context. However, it does not describe the export format, whether the operation has side effects (e.g., file generation), response structure, or any rate limits. This is a moderate disclosure but leaves important gaps.

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, front-loaded with the main purpose, and every sentence adds useful information: what the log contains, filtering options, and pagination support. No wasted words 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?

This is an export tool with 5 optional parameters and no output schema. The description explains the log content and filtering/pagination, but it does not specify the output format (e.g., JSON, CSV, file download) or the response structure. Since the output schema is absent, the description should have provided more detail on return values to be 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?

The input schema has 100% description coverage, so the schema already documents all five parameters. The description adds value by grouping parameters (date range, patient filter, pagination) and clarifying their purpose, but it does not add syntax or format details beyond what the schema provides. Baseline 3 is appropriate when the schema is complete; the grouping is a slight enhancement but not enough to warrant a 4.

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 ('Export') and resource ('the local HIPAA §164.312(b) audit log'), and clarifies what the log contains ('Every read and write of PHI is recorded here'). It clearly distinguishes this from sibling tools, which are mostly list/get operations for other entities (notes, invoices, clients, etc.).

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 clear usage context: it tells users to filter by date range using date_from/date_to and by patient using client_id, and mentions pagination via limit/offset. It does not explicitly state when not to use this tool or compare it to alternatives, but the tool is sufficiently unique that usage intent 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?

With no annotations provided, the description carries the burden of disclosing behavior. The verb 'Check' implies a non-destructive read operation, but it does not specify what the return value looks like or any potential side effects (e.g., network calls). This is a acceptable minimal disclosure but not rich.

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, clear sentence with no filler. It is front-loaded with the action and resource, making it easy to parse quickly.

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 status check with no output schema, the description is nearly complete. It clearly states what it does. However, it lacks contextual details like when to use it in the broader auth workflow or what the response contains, which 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?

The tool has zero parameters, so the baseline is 4. The description correctly needs no parameter information. There is no schema to clarify, and the description adds no unnecessary detail.

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 a specific action ('Check') and resource ('connector is authenticated with IntakeQ'), making its purpose unambiguous. It naturally distinguishes itself from sibling tools like set_api_key and clear_api_key, which perform mutations rather than status checks.

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 to verify authentication status, but provides no explicit guidance on when to use it versus alternatives, nor any mention of prerequisites. For a simple status check, this is adequate but not explicit about the workflow (e.g., checking before making API 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?

With no annotations present, the description must fully disclose behavioral implications. 'Clear' implies a destructive or state-changing effect, but the description does not mention that clearing the key will break authenticated API calls until a new key is set, nor does it indicate irreversibility or any confirmation steps. This leaves the agent without important behavioral context.

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

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

The description is a single, front-loaded sentence with no filler. It conveys the entire purpose efficiently and is appropriately sized for a tool with no parameters.

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

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

For a tool this simple (0 params, no output schema, no annotations), the description is minimally adequate but has gaps. It fails to explain the broader impact (e.g., subsequent auth_status will show unauthenticated, set_api_key must be used to reconfigure) and lacks any mention of success/failure behavior. These omissions are noticeable given the lack of annotations, though the tool's simplicity mitigates the severity.

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 effectively 100% (empty schema). The baseline for 0 params is 4, and the description adds no parameter information because there are none to describe, so this score 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 uses a specific verb ('Clear') and a clear resource ('stored IntakeQ API key'), making the tool's function unambiguous. It naturally distinguishes from siblings like 'set_api_key' and 'auth_status', which are related but have different actions.

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 guidance is provided on when to use this tool versus alternatives, nor any context about prerequisites or the need to reconfigure after clearing. The description simply states the action without indicating appropriate use cases, such as when an API key is invalid or needs to be reset.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that all fields are required, but that is already evident from the schema. It does not disclose side effects (e.g., whether creating an appointment triggers notifications, sends emails, or has irreversible consequences). The tool clearly performs a write operation, but additional behavioral context is missing.

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 concise sentence that immediately identifies the action and system. It is front-loaded and contains no redundant or irrelevant content. It fully maximizes conciseness, even if it lacks depth in other areas.

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 absence of an output schema and annotations, the description is insufficient for a tool with 8 required parameters. It does not explain what the response looks like, what errors might occur, or any prerequisites. A create operation of this complexity needs more context to guide an agent toward correct invocation and result interpretation.

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 each parameter having a meaningful description. The tool description adds no additional parameter context beyond the schema. The statement 'All fields are required' merely repeats the 'required' array in the schema. Therefore, the description does not enhance parameter understanding beyond what is already structured.

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: 'Create a new appointment in IntakeQ.' The verb 'Create' and resource 'appointment' are specific, and it is distinct from sibling tools like update_appointment, get_appointment, and list_appointments. There is no ambiguity about what this tool does.

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 offers no guidance on when to use this tool versus alternatives. It does not mention that update_appointment should be used for modifying existing appointments, nor does it note prerequisites such as having valid client, service, or practitioner IDs. A tool as complex as creating an appointment would benefit from explicit 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?

No annotations are provided, so the description carries the full burden. It only says 'Get' which implies a read operation, but it does not disclose any additional behavioral traits such as whether the appointment data is returned in full, whether invalid IDs cause errors, or any authentication requirements. The description adds almost nothing beyond the verb itself.

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 concise sentence with no fluff. It is appropriately sized for a simple get-by-ID tool and delivers the essential information efficiently.

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's simplicity (one parameter, read-only intent), the description is minimally adequate. However, it lacks any context about return values, error behavior, or the broader workflow, and does not reference sibling tools. It feels terse even for a simple tool, so it does not fully satisfy the completeness criterion.

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%: the property appointment_id is described as 'The IntakeQ appointment ID'. The tool description's 'by ID' merely repeats this. The baseline is 3 because the schema handles parameter documentation completely; the description does not add extra meaning.

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 action (get), the resource (a single appointment), and the qualifier (by ID). It distinguishes itself from sibling tools like list_appointments (which lists multiple) and create/update_appointment (which mutate).

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 usage when you need a single appointment by its ID, but it does not explicitly mention when not to use it or name alternatives such as list_appointments for browsing. It lacks the explicit referral to other tools that would earn a higher score.

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

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

With no annotations, the description carries the full burden. It adds valuable behavioral context by mapping BillingType and LinkedClientRelationshipType enum values in the response. It does not cover authentication, errors, or side effects, but for a simple read-only get operation this is reasonably transparent.

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

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

The description is concise and front-loaded with the primary purpose. The response field reference is well-structured and directly useful, with no redundant 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 single-get tool with one parameter and no output schema, the description is largely complete. It provides the necessary purpose and even includes a response field reference. It would benefit from explicit usage guidance relative to siblings, but it is not deficient.

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% for the single client_id parameter. The description merely repeats 'by ID' without adding further semantic detail beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool gets a single client by ID and includes the full profile. This distinguishes it from list_clients and other get_* tools, 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 implies usage for retrieving an individual client's full profile but does not explicitly mention when to use this tool versus list_clients or other alternatives. No exclusions or alternatives are provided.

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

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

The description discloses that the data is PHI and every call is audit-logged, which is a meaningful behavioral trait beyond the schema, especially because no annotations are provided. It does not detail error handling or response structure, but the audit-log warning adds valuable context.

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

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

The description is two sentences: the first states the core purpose, the second a critical caution. Every word earns its place, and the key information is front-loaded.

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 getter with no output schema, the description covers the essential purpose and a key behavioral trait. It could mention that the return value is the full form submission, but the wording 'Get a single intake form submission' makes that implicit. Overall, it is reasonably 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 input schema already describes form_id as 'The IntakeQ intake form ID' (100% coverage). The tool description only restates 'by ID' without adding new semantic detail, so the baseline 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 clearly states the action (Get), the resource (a single intake form submission), and the identifier (by ID). It distinguishes from sibling tools like list_intake_forms (list vs single) and get_note (different resource).

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 is implied: 'Get a single intake form submission by ID' suggests using this when you have a specific form ID. However, it does not explicitly contrast with alternatives such as list_intake_forms for discovering IDs or mention when not to use it.

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

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

With no annotations, the description must carry the full burden. It communicates that this is a read operation ('Get') with no side effects, but does not disclose return format, error behavior (e.g., 404 if not found), or authentication requirements. Minimal but not misleading.

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 wasted words. It states the action and scope 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 simple get-by-ID tool with one parameter, the description is mostly complete. It lacks explicit return type or error handling, but the operation is straightforward and the schema covers the parameter. The sibling list_invoices provides differentiation.

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 parameter description ('The IntakeQ invoice ID') is sufficient. The tool description adds no additional meaning beyond the schema, 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 uses a specific verb ('Get') and resource ('a single invoice'), clearly distinguishing it from the sibling 'list_invoices' tool. It precisely states the scope (single by ID), making the tool's 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 clearly implies usage when a specific invoice ID is known, distinguishing it from listing tools. However, it does not explicitly mention alternatives (e.g., use list_invoices to find IDs) or state when not to use this tool.

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

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

With no annotations provided, the description carries the full burden. It adds a critical behavioral disclosure: 'PHI — every call is audit-logged.' This warns the agent about sensitivity and audit side-effects. However, it does not cover error behavior, return format, or permissions, leaving some gaps.

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: the first states purpose, the second adds a crucial caveat. It is front-loaded with the key action and resource, with zero filler or redundant details.

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 get-by-ID tool with one parameter and no output schema, the description is largely complete. It explains what the tool does and the important PHI/audit context. It could be improved by noting return format or error behavior, but given the low complexity, it is adequate.

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 already provides full coverage (100%) with a clear description for note_id ('The IntakeQ note ID'). The tool description adds no new parameter-specific meaning beyond that, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('Get'), a specific resource ('clinical note'), and scope ('by ID'). It clearly distinguishes from sibling tools like list_notes (list vs. single) and other get_* tools (note vs. form/invoice/client).

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

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

The phrase 'by ID' implies the tool should be used when the caller already has a note ID, which gives some usage context. However, it does not explicitly mention when to use this tool versus list_notes or other getters, nor does it provide exclusions or alternatives.

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?

Since no annotations are provided, the description carries the burden of disclosing behavior. It states the required filter constraint, which is key behavioral information. However, it does not mention pagination behavior (despite a page parameter in the schema), default page size, or what the response contains. This is a partial disclosure for a list operation.

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, front-loaded with the core action and immediately followed by the essential usage constraint. There is no wasted wording or repetition of schema details, making it appropriately concise.

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 six parameters and no output schema, the description is too sparse. It fails to explain pagination (e.g., how the page parameter works, result limits), whether multiple filters are combined (AND/OR), or what response format to expect. The schema covers parameter descriptions, but the behavioral context around listing is incomplete.

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

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

Schema coverage is 100% for all six parameters, so the baseline is 3. The description adds critical cross-parameter semantics by specifying that at least one of clientId, startDate, or endDate must be provided—this is not evident from the schema, which marks none as required. This goes beyond what the schema offers, justifying a 4.

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 'List appointments' clearly identifies the action and resource. The follow-up constraint about required filters adds scope, distinguishing it from get_appointment (which retrieves a single appointment). However, it doesn't explicitly differentiate from other list tools like list_notes or list_invoices, though the resource name is unambiguous.

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

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

The description implies usage: you should call this when you want appointments and must provide at least one of clientId, startDate, or endDate. It does not state when to prefer an alternative (e.g., get_appointment for a specific appointment) or provide exclusions, so it relies on the agent to infer from sibling tool names.

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

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

With no annotations, the description must disclose behavioral traits. It does disclose the pagination cap (up to 100 results per page) and provides a response field reference for interpreting enums. However, it does not mention whether search supports partial matches, case sensitivity, sorting defaults, or any potential side effects (though none are expected for a list call). The provided context is useful but not comprehensive.

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. The purpose is stated in one sentence, the pagination constraint in another, and the response field reference is clearly separated. Every line adds value without redundancy, making it easy to scan.

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 list tool with only two optional parameters and no output schema, the description does a good job. It explains the pagination behavior and clarifies two often-ambiguous enum fields in the response. It could be more complete by explicitly stating that all clients are returned when no search is provided, but the schema's optional parameters imply this. Overall, it is sufficient for a tool of this complexity.

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

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

The input schema already provides full descriptions for both parameters ('Page number (1-based)' and 'Name or email search term'), so schema coverage is 100%. The description adds no additional parameter semantics, such as search matching behavior or interaction between parameters. This meets the baseline for full schema coverage.

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

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

The description starts with a clear verb+resource combination: 'Search/list clients in the connected IntakeQ account.' It also states the pagination limit, making it distinct from sibling tools like get_client (which presumably fetches a single client). The purpose is immediately understandable.

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 usage for searching or paging through clients, and the pagination limit gives a practical constraint. However, it does not explicitly mention when to use this tool instead of alternatives like get_client, nor does it discuss search behavior (partial matching, optional criteria). It provides no exclusionary guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses key behaviors: returns only references, never downloads files, and requires clientId. This adds meaningful context beyond the schema, though it could mention pagination or error conditions. No contradiction with annotations (none exist).

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, front-loaded with the primary action, and every sentence adds value. It avoids redundancy and clearly communicates the tool's purpose and key constraints.

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 simple tool with one parameter and no output schema, the description covers the return fields and the no-download behavior, making it fairly complete. It could add details on pagination or limits, but these are not critical for a straightforward metadata list operation.

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 already describes clientId as mandatory and required, and the description repeats this without adding new details. Since schema coverage is 100%, the baseline is 3; the description does not enrich parameter meaning further.

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 'List file metadata for a client' with a specific verb and resource. It distinguishes itself from sibling tools by specifying it returns references only (Id, FileName, etc.) and never downloads files, making its scope 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 implies usage by stating it lists file metadata for a client and requires clientId. It does not explicitly mention alternatives or exclusions, but the focus on metadata references and no-download behavior provides clear context. Lacks explicit 'use when' or 'instead of' guidance, so not 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?

The description discloses that the tool handles PHI and that every call is audit-logged, which is valuable security behavior beyond the schema. However, it does not mention other behavioral aspects like default filtering to only submitted forms or pagination, leaving these details to the 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?

The description is two sentences total, which is extremely concise. The first sentence states the purpose and the second adds a crucial PHI/audit warning, with 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?

The description is minimal but the schema provides detailed parameter information, covering filtering options and pagination. However, with no output schema, the description does not clarify the return format or the default behavior around the 'all' parameter (i.e., whether non-submitted forms are included), which is a gap for a list 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 schema descriptions cover all 7 parameters with 100% coverage, so the description does not need to repeat them. The description adds no parameter-specific meaning but also does not need to, as the schema is thorough and self-explanatory.

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 with a specific verb ('list') and resource ('intake form submissions'), which effectively distinguishes it from sibling tools like 'get_form' and 'send_intake_form'. There is no ambiguity about what the tool does.

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 offers no explicit guidance on when to use this tool versus alternatives, such as 'get_form' or 'list_questionnaire_templates'. Usage is only implied by the verb 'list' and the tool name, without any stated exclusions or alternatives.

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?

No annotations are present, and the description adds no behavioral details such as pagination, default result limits, sorting, or the fact that filters are supported. It merely restates the function's basic action.

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, concise sentence that front-loads the action and resource. No wasted words or redundant 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?

Given the tool has 9 optional filter parameters, no output schema, and no annotations, the description is too minimal. It fails to mention return format, pagination, or that the filters exist, making it inadequate for an agent to fully understand the tool's capabilities.

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 provides descriptions for all 9 parameters, covering 100% of them, so the baseline is 3. The description itself adds no parameter-level detail, but the schema already documents each filter and its 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?

The description uses a specific verb 'List' with the resource 'invoices', and clarifies the source as the 'connected IntakeQ account'. It clearly distinguishes from the sibling tool get_invoice, which retrieves a single invoice.

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 guidance is provided on when to use this tool versus alternatives like get_invoice. The description does not mention whether this is for bulk retrieval, or mention any filtering or pagination considerations.

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

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

With no annotations, the description must carry the burden of behavioral disclosure. It conveys a read-only 'List' operation, but does not explicitly state safety (non-destructive), return format, or any edge cases. The added context about LocationId is useful, but the description remains minimal and does not disclose beyond what the name implies.

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 short sentences, front-loaded with the main purpose, followed by a practical use case. Every word earns its place with no fluff or repetition.

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-parameter list tool, the description adequately explains what it does and why to call it, including a concrete downstream use. It lacks an explicit statement about return structure, but the mention of LocationId and the tool's simplicity make it sufficiently 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 has zero parameters, so there is nothing to explain. Per rubric, 0 parameters yields a baseline of 4. The description does not need to add parameter meaning, and the empty schema is consistent.

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 'List locations configured in the IntakeQ account.' This is a specific verb ('List') and resource ('locations'), and it distinguishes itself from sibling tools by targeting locations specifically, which no other sibling does.

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 'Call this before create_appointment to find a valid LocationId.' This provides clear when-to-use guidance and ties it to a specific downstream tool, making it highly actionable for an agent deciding 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?

With no annotations provided, the description carries the full burden. It discloses that calls are audit-logged due to PHI and that notes are read-only, which are important behavioral traits. It does not mention pagination behavior or return shape, but the schema covers pagination via the page parameter.

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

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

The description is three concise sentences, each providing distinct value: the action, the PHI/audit warning, and the read-only nature. There is no redundancy or 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?

The tool has 7 optional parameters and no output schema, so the description should provide enough context to understand the tool's role. It gives key behavioral warnings but does not explain filtering options or response format, though the schema covers parameters. It is minimally sufficient but lacks guidance on use cases.

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 parameters are already well-documented. The description adds no extra semantics about parameters like date formats or filtering behavior beyond what is in the schema, thus the baseline 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 phrase 'List clinical notes' clearly states the action and resource, and it is distinct from the sibling tool 'get_note' which presumably retrieves a single note. However, it does not explicitly contrast itself with alternatives or mention the filtering capabilities covered by 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 gives no guidance on when to use this tool instead of get_note or other listing tools. It only says what it does, not under what circumstances it is preferred.

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?

No annotations are provided, so the description carries the full burden. It discloses that the operation lists all practitioners, implying a read-only, safe action. However, it does not mention authentication requirements, pagination, or output formatting, which would improve transparency.

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 redundancy. The first states the function, the second gives actionable usage guidance. Every word earns its place, and the most important info is front-loaded.

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 or annotations, the description is the sole source of information. It clearly explains the purpose, usage timing, and how to use the output. It omits potential details like pagination or authentication, but for a simple list-all tool, the description is sufficient for most contextual needs.

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

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

There are zero parameters, so the baseline is 4. The description adds significant value by telling the agent that the response contains a valid PractitionerId, which is directly useful for the follow-up create_appointment call. This goes beyond the empty 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?

Verb 'List' + resource 'practitioners' clearly states the operation. Scoping to 'IntakeQ account' and the explicit tie to 'find a valid PractitionerId' before create_appointment distinguishes this from sibling list tools (list_notes, list_clients, etc.).

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

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

Provides explicit usage context: 'Call this before create_appointment to find a valid PractitionerId.' This tells the agent exactly when to use it. It lacks explicit alternatives or when-not-to-use, but the scenario is very concrete.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the tool lists all available templates, indicating a read-only operation with no filtering. It does not mention potential nuances like archived templates or pagination, but given the simplicity of the operation, the core behavior is transparent.

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

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

The description is a single, concise sentence that immediately identifies the action, resource, and scope. Every word earns its place, and there is no redundant or irrelevant content.

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 list tool with no parameters and no output schema, the description is adequately complete: it states what is listed and the scope. It does not describe the return structure, but that is a minor omission for such a straightforward operation.

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 0 parameters, and the baseline for 0 params is 4. The description adds no parameter-specific details, but none are needed since the tool takes no arguments.

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 verb 'List', the specific resource 'questionnaire templates', and the scope 'all in the IntakeQ account'. It distinguishes this tool from sibling list tools by naming a distinct entity (questionnaire templates vs. intake forms, notes, invoices, etc.).

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 usage when an agent needs to enumerate questionnaire templates. Although no explicit alternatives or exclusion criteria are given, the scope ('all') and resource are unambiguous, providing clear context for when this tool is appropriate.

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

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

With no annotations, the description carries the burden. It implies a read-only operation and hints that the response includes ServiceIds, but does not disclose auth requirements, rate limits, or the full output structure. This is acceptable for a simple list tool but not richly transparent.

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

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

Two short sentences, front-loaded with the core purpose and followed by a practical usage hint. Every word earns its place with no 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 list tool with one optional parameter and no output schema, the description covers the essential context: what it lists and why to call it. It stops short of detailing the response format, but the explicit mention of finding ServiceId provides a key behavioral clue.

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 fully documents the only parameter (practitionerEmail) with a clear filtering description. The tool description adds no additional parameter semantics, so 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 uses the specific verb 'List' with the resource 'services' and clearly defines scope as 'configured in the IntakeQ account.' It also links the tool to a concrete use case (finding a valid ServiceId before create_appointment), which eliminates ambiguity.

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 states 'Call this before create_appointment,' giving the agent a clear when-to-use directive. It does not mention alternatives or when not to use, but there are no sibling tools that overlap with this functionality.

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?

No annotations are provided, so the description must carry full behavioral disclosure. It only states 'send' without mentioning side effects (e.g., does it send an email? create a record?), return value, or requirements like email deliverability. This is a significant gap for a mutating action.

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 short sentences, front-loaded with the primary action. The second sentence efficiently conveys the parameter requirement. 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?

Given the tool's moderate complexity, the description covers the purpose and the key parameter logic. However, without annotations or an output schema, it lacks information about return values, side effects, and any prerequisites. This leaves room for ambiguity in agent invocation.

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

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

Schema description coverage is 100%, so each parameter is documented. The description adds extra value by clearly expressing the mutually exclusive relationship between ClientId and ClientName+ClientEmail, which is not fully explicit in the individual parameter descriptions. This improves parameter understanding.

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 action 'Send an intake form to a client' with a specific verb and resource. It distinguishes itself from sibling tools like list_intake_forms and get_form by focusing on the sending action.

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

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

The description provides clear context for when to use this tool: to send an intake form to a client. It also specifies the parameter combination rule (QuestionnaireId plus either ClientId or ClientName+ClientEmail), which guides usage. However, it does not explicitly mention alternatives or when not to use this tool.

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

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

With no annotations, the description carries the burden of disclosing behavior. It states two key behaviors (storing the key and verifying connectivity), but does not mention side effects like overwriting an existing key, persistence, or error handling, leaving some uncertainty.

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, front-loaded sentence that directly states the tool's core function without superfluous words or repetition.

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 configuration tool with one parameter and full schema coverage, the description provides sufficient context including the connectivity check. It doesn't detail return values, but the absence of an output schema makes that acceptable.

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 description for the single parameter (api_key) is explicit and includes where to find the key, achieving 100% coverage. The tool description adds no additional parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as storing an IntakeQ API key and verifying connectivity, using specific verbs and a resource. It implicitly distinguishes from sibling tools like auth_status and clear_api_key, though it doesn't explicitly differentiate them.

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 purpose is clear enough that an agent can infer when to use it (when setting up or updating the API key), but there is no explicit guidance about when not to use it or when to prefer alternatives like auth_status or clear_api_key.

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?

No annotations are provided, so the description carries the transparency burden. It discloses required fields and mutation constraints, but omits side effects, response format, or whether this is a full vs partial update.

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 succinct sentences contain all necessary information without redundancy, with the primary action stated first.

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

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

The tool has 7 parameters, no output schema, and no annotations. The description provides core requirements and constraints but lacks important context such as whether unspecified optional fields are reset by the PUT operation.

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, but the description adds key context: Id and UtcDateTime are required, and client/practitioner cannot be changed (which are not parameters). This goes beyond the schema's basic field labels.

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 'Update an existing appointment via PUT', identifying the verb, resource, and HTTP method. It distinguishes from siblings like create_appointment by focusing on existing appointments, and notes the constraint on client/practitioner changes.

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 implies usage for updating existing appointments, but does not explicitly compare to create_appointment or other alternatives. The constraint 'Cannot change client or practitioner' provides a clear exclusion for certain update attempts.

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