mental-health-care

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

Annotations indicate readOnlyHint=true, and the description goes beyond by detailing the content retrieved (identity, services, crisis resources). No contradictions. It also notes it's optional and step 1 of a workflow.

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 moderately concise but includes a structured list and an example. While it could be slightly shorter, the structure aids readability.

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

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

With no output schema, the description fully explains the return content. It also provides workflow context (step 1 of explore_information). No gaps identified.

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 with 100% schema coverage, so the baseline is 4. The description doesn't need to add parameter info, but it implicitly confirms no arguments via the example call 'about_emora({})'.

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 explicitly lists what the tool returns: identity, services, states served, insurance, age ranges, key facts, crisis resources, and links. It distinguishes itself from siblings like 'get_crisis_resources' by being a combined site-info and services catalog.

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

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

Provides clear 'Use when' scenarios (e.g., 'what is Emora?') and explicitly states 'Don't use when' (if site context already exists). This helps the agent choose the right 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?

Description indicates a mutation (booking creation) but annotations set readOnlyHint=true, a direct contradiction. Description adds no additional behavioral context beyond the contradictory hint.

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?

Structured with step label, critical note, usage conditions, and example. Each sentence serves a purpose; no fluff. Front-loaded with most important 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?

Covers usage context, prerequisites, and return behavior (URL). However, due to annotation contradiction (readOnlyHint vs booking action), it leaves ambiguity about whether the tool actually books or just generates a URL. No error handling or post-booking steps mentioned.

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 low (20%), but description explains key parameters (date_time, insurance) via example and notes that date_time should be passed exactly as received. Provides a concrete call example. Adds significant value beyond schema.

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

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

States it returns a booking URL to pre-fill provider, time slot, state, and insurance for a quick checkout. Clearly identifies as step 4 of a multi-step process and differentiates from siblings like check_availability and find_provider.

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

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

Explicitly says when to use: 'The user has picked a provider from find_provider AND a time slot from check_availability.' Also lists prerequisites and an exclusion: 'Don't use when: You don't have a provider_id + state + appointment_type.'

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?

Description indicates a write operation (booking a session) but the annotation declares readOnlyHint=true, contradicting the tool's actual behavior. This is a serious inconsistency that could mislead the AI agent.

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 very concise (3 sentences plus example), front-loaded with the main action, and every sentence serves a purpose (purpose, usage, example).

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

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

The description is complete for a tool that returns a URL: it states the return value and warns not to navigate programmatically. However, the contradiction with annotations reduces trust in completeness.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds an example showing parameter usage but does not provide additional semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'Pre-fills the booking URL for a 45-minute Clinical Matching Session'. It distinguishes the tool from its sibling by specifying that it is step 2 of a process and contrasts with book_appointment for direct provider booking.

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 provides when to use ('user wants Emora to find the right long-term provider') and when not to use ('if user has already picked a specific provider – use book_appointment'). It also includes an example invocation.

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

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

Annotations already declare readOnlyHint=true, and the description confirms a safe read operation. It adds behavioral context about the two modes (specific page vs. list) and the pagination behavior in description, though pagination details are minimal.

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?

Extremely concise: three sentences plus a usage guideline block and an example. Every sentence is purposeful, no redundancy. Structure is clear and 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?

Given 4 parameters and no output schema, the description covers the essential usage patterns, distinguishes from siblings, and provides an example. Could benefit from mentioning response structure or pagination details, but overall 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?

Input schema has 100% description coverage, so baseline is 3. The description does not add significant meaning beyond schema, except for the example usage showing how slug and collection combine. Schema already explains each parameter adequately.

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?

Clearly states it browses specific page types (conditions, specialties, insurance) and returns either a specific page by slug or a paginated list. Distinguishes from blog articles and sibling tools like search_content.

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 provides 'Use when' and 'Don't use when' scenarios, including a concrete alternative (search_content) for different content types. This gives clear decision criteria for the agent.

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?

Describes real-time, read-only behavior returning 10 open slots. Annotations have readOnlyHint=true, consistent. Includes example for clarity. 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?

Purpose and guidelines are front-loaded. Example is helpful but adds length. Generally well-structured with minimal waste.

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

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

Covers purpose, when/not to use, and provides example. Lacks return structure details beyond 'next 10 open slots with start timestamps' but sufficient for simple tool with no output schema.

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

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

Schema coverage is 0%, description only adds context via example showing state, appointment_type, and provider_id. Does not explain what state or appointment_type represent semantically beyond enums.

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?

Clearly states it's for real-time availability for one specific provider, returning next 10 open slots. Distinguishes from siblings like find_provider and book_appointment.

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

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

Explicitly says to use when user has selected a provider and needs slot data before booking, and warns not to use without a provider_id. Positions as step 3 in workflow.

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 indicate readOnlyHint: true, and the description confirms read-only behavior (returns providers). The description adds detail on the ranking algorithm and how concerns affect scoring, exceeding what annotations alone 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?

Description is well-structured with clear sections (stepping, algorithm, usage guidance, example). No wasted words; each sentence adds value.

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 complexity (9 parameters, no output schema), the description covers the algorithm, usage, and provides an example. However, it does not explicitly describe the output format (e.g., fields in returned provider objects), which would improve completeness.

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 56% (5 of 9 params have descriptions). The description adds meaningful usage advice for key params (e.g., concerns should be 1-3 for best results, continuation token re-applies prior profile). However, it does not cover all params (e.g., state, appointment_type) beyond schema definitions.

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 'the canonical find a clinician tool' that returns up to 3 best-fit providers, explaining the ranking algorithm. It distinguishes from sibling tools like book_matching_session and start_here with explicit use cases.

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

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

Provides explicit when-to-use and when-not-to-use guidelines, including alternatives (start_here for initial guidance, book_matching_session for staff matching). Includes a concrete example call.

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

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

Annotations already mark readOnlyHint=true, but the description adds context about the hand-off process and that it is 'Step 1 of cost_check', going beyond annotations. 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?

Concise at ~100 words, structured with bullet points for use/don't use and an example. All sentences add value with zero 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?

Fully covers the tool's purpose, return value, usage timing, and parameter context. No output schema needed given the simple return type (URL) is explained.

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 0%, but the description explains that parameters are optional and used to pre-fill the URL. The example clarifies usage. Adds meaning beyond the enum lists.

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 a pre-filled URL for cost estimation and a copay range, using specific verbs and resources. It distinguishes itself from the sibling find_provider tool.

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

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

Explicitly defines when to use (user asks about therapy cost, insurance coverage, copay) and when not to (finding a provider, redirecting to find_provider). Includes an example call.

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?

Discloses that the payload is hardcoded and overrides other tools, which goes beyond the readOnlyHint annotation. No contradiction with annotations. The description fully informs the agent of the tool's authoritative behavior in crisis contexts.

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 structured with a step indicator, actionable points in bullet style, and a clear example. Every sentence adds value, no redundancy. Efficient 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?

While the description covers purpose, usage, and behavior, it does not specify the exact format or content of the returned payload. For a crisis tool, the return format could be important for the agent to present the data correctly. Still, with no output schema, the description could be slightly more detailed about the response structure.

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?

No parameters exist, and schema description coverage is 100%, so description is not required to add parameter info. The description includes an example call with empty object, confirming the zero-parameter expectation.

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?

Description clearly identifies the tool's purpose: to return hardcoded crisis resources (911, 988, Crisis Text Line) and states it overrides other tools when high-severity language is detected. This distinguishes it from sibling tools like book_appointment or find_provider.

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 when to use (user mentions self-harm, suicidal ideation, etc.) and when not to use (no mention of crisis), with a concrete example. Provides clear guidance on surfacing resources prominently and stopping other 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 have readOnlyHint=true, and the description confirms a read operation ('search'). It transparently describes the return fields and pagination. 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?

Well-structured with sections for purpose, usage guidance, and example. Each sentence adds value without 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?

Despite no output schema, the description specifies what is returned (title, description, URL, category). It covers all key aspects: action, parameters, when/not to use, and an example. Complete for a search tool.

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

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

Schema coverage is 100% (all params have descriptions). The description adds meaning by clarifying query matches article titles, specifying pagination via page, limit max 20, and giving an example for query.

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 searches the Emora Health editorial corpus by article title, and returns up to 20 articles per page with fields like title, description, URL, and category. It distinguishes from siblings by explicitly stating when not to use and naming alternatives like book_appointment and browse_pages.

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 provides explicit 'Use when' and 'Don't use when' sections, referencing specific sibling tools and giving concrete examples of appropriate queries.

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?

Description complements readOnlyHint annotation by detailing that the tool performs a parallel lookup and is optimized for the first turn, replacing 2-3 sequential lookups. It does not contradict annotations; however, it does not mention any potential rate limits or data freshness, but given readOnlyHint, this is acceptable.

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

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

Front-loaded with tool purpose in bold, followed by brief explanation, usage guidelines, and example. Every sentence is informative without redundant information. The structure is clean and efficient.

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

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

For a tool with no output schema, description explains that it returns a recommended path (crisis, evaluation, self-help, or mixed) with concrete next steps. It covers inputs and high-level output sufficiently for a first-step tool, though more detail on return structure could help.

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% (all parameters described). Description adds value by providing an example call and contextualizing the parameters (e.g., state and age for filtering, concern for lookup). The example clarifies how parameters are used together, which goes beyond schema descriptions.

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?

Description explicitly states tool is the 'best first action' for a user describing a concern, performs parallel lookup across crisis screening, provider availability, and article corpus, and distinguishes itself from siblings by advising 'Call this FIRST'. It uses a specific verb ('runs a parallel lookup') and resource domains.

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?

Includes explicit 'Use when' and 'Don't use when' sections, naming alternatives such as find_provider, search_content, check_availability, and book_appointment. Gives clear context for when to use this tool vs. others.

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