lyra-mcp-server

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

Annotations declare destructiveHint=false, establishing safety. Description adds critical auth requirement ('Requires API key') and clarifies what gets created (specific item types). Does not disclose return format, idempotency behavior, or side effects, but meets baseline expectations given annotation coverage.

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

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

Two sentences, zero waste. First sentence establishes function and valid categories; second states the auth prerequisite. 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?

Complete for a 4-parameter create operation with excellent schema coverage. Describes what is created and auth requirements. Minor gap: no mention of return value or success behavior, though this is acceptable given the straightforward CRUD nature and lack of 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?

With 100% schema coverage, baseline is 3. Description adds value by mapping enum values to natural language concepts ('gift idea' for 'gift_ideas', 'boundary' for 'boundaries'), making the category parameter semantics clearer than the schema's raw enum values alone.

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 uses specific verb 'Add' with clear resource 'Lyra profile item' and enumerates exact categories (like, dislike, gift idea, boundary) that map to the schema enum. Clearly distinguishes from siblings lyra_add_link (links) and lyra_add_school (schools) by focusing on 'profile' content items.

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?

Lists specific item categories that guide when to use the tool (for adding preferences/boundaries), and states the prerequisite 'Requires API key'. Lacks explicit 'when not to use' or named alternatives, but provides clear contextual guidance through category enumeration.

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 adds authentication requirements ('Requires API key') not present in annotations, but does not disclose other behavioral traits like idempotency, error conditions, or side effects beyond the non-destructive hint already provided.

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 consists of two efficient sentences with zero redundancy; the core action is front-loaded in the first sentence, and the critical prerequisite follows immediately.

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

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

Given the moderate complexity (4 params, 75% schema coverage, no output schema), the description adequately covers the core use case and auth requirements. It could be improved by explicitly documenting the link_type enum values since the schema omits their descriptions.

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

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

With 75% schema coverage, the baseline is 3. The description adds semantic value by listing link categories ('wishlist, shop, or link'), which implicitly maps to the link_type enum options lacking individual schema descriptions, partially compensating for the coverage gap.

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 ('Add'), the specific resource types ('wishlist, shop, or link'), and the target ('Lyra profile'), effectively distinguishing it from sibling tools like lyra_add_item and lyra_add_school.

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 a prerequisite ('Requires API key') but lacks explicit guidance on when to use this tool versus alternatives (e.g., lyra_add_item for products vs. external links) or 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?

Adds the API key authentication requirement not present in annotations. Aligns with destructiveHint=false (non-destructive addition). However, it fails to disclose idempotency behavior, error conditions (e.g., duplicate school), or what constitutes a successful 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?

Extremely concise at two sentences. Information is front-loaded with the primary action stated first. The second sentence ('Requires API key.') is functional but could be smoother; no redundant or wasted text.

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?

Adequate for a simple 4-parameter creation tool with full schema coverage. Missing behavioral context like idempotency guarantees and return value description (no output schema exists to compensate). Sufficient for basic usage but lacks operational depth.

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

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

With 100% schema coverage, the schema adequately documents all parameters. The description adds minimal semantic value beyond the schema, only implicitly referencing the 'connection' concept which maps to the relationship parameter. Baseline score appropriate given schema quality.

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 the action ('Add') and resource ('school connection to a Lyra profile'), distinguishing it from sibling tools like lyra_remove_school. However, it doesn't clarify the distinction from lyra_add_item or when to prefer this over lyra_update_profile for school-related 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?

States the prerequisite ('Requires API key') but provides no guidance on when to use this tool versus alternatives like lyra_update_profile or lyra_add_item. No mention of prerequisites like profile existence or school validation.

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 destructive operation; description confirms and adds details: cancellation reason in audit log, invite preservation, RSVP page update, authentication requirement. No contradiction.

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

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

Four sentences, each earning its place. First sentence states core purpose. Remaining sentences add essential behavioral and usage details 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?

For a cancel action with no output schema, description covers preconditions, side effects, audit trail, and authentication. Sufficient for an AI agent to invoke correctly.

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

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

Schema has 100% coverage; description adds value by explaining purpose of reason (audit, shown to invitees) and alternative API key delivery (header). Enhances understanding 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?

Clearly states the verb 'cancel' and the resource 'gathering'. Differentiates from siblings like finalize or reschedule by specifying it works from non-terminal states.

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 lists applicable states (draft, awaiting_responses, live, rescheduled), implying when not to use (terminal states). Does not explicitly name alternative tools but provides clear 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?

Description mentions storing an encrypted refresh token, indicating a write/mutation side effect. However, annotations claim readOnlyHint=true, which is a direct contradiction (annotation_contradiction=true). Annotations already provide readOnlyHint, but description contradicts it.

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

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

Three sentences, somewhat front-loaded with purpose but includes extraneous version references (P2, P7). A cleaner, more concise description would be more effective.

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 no output schema, description explains return type (URL) and post-consent behavior. However, it does not describe what happens on error, whether the URL expires, or how to handle the callback. The behavioral transparency issue reduces 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 baseline 3. Description does not add much beyond schema: it explains api_key is for authentication and notes provider currently limited to google, which schema already states. No additional format or constraint details.

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 returns a URL to connect a calendar provider, listing specific providers (Google, Microsoft, Apple). Distinguishes from sibling tools like lyra_disconnect_provider. However, version-specific notes ('in P2', 'in P7') add unnecessary detail.

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 prerequisites: user must be signed in to checklyra.com and the calling agent needs API key authentication. Implicitly suggests when to use (when a calendar connection is needed) but does not explicitly say when not to use or mention 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?

Discloses draft state, flow, authentication requirement, and that free-text fields are user-generated. Adds value beyond annotations (readOnlyHint=false, destructiveHint=false) by explaining the lifecycle and constraints.

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, three sentences plus a note, front-loaded with purpose. Every 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?

Covers creation flow, state, and finalization well. Lacks specification of return value (e.g., gathering ID), but given no output schema and 12 parameters, it is fairly complete.

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

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

Schema coverage is 83%, so baseline is 3. The description adds little beyond the schema; it mentions 'optional proposed time slots and invitees' but doesn't elaborate on format or purpose. The flow guidance is helpful but not parameter-specific.

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 states it creates a gathering in 'draft' state with optional slots and invitees. It distinguishes from sibling tools like lyra_finalise_gathering (locks slot) and lyra_update_gathering (updates).

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 describes the agent-driven flow: propose attendees → check availability → call with 2-3 slot candidates and invitee IDs. Mentions lyra_finalise_gathering for finalization, providing clear context on when to use this tool versus 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?

Annotations already mark destructiveHint as true, but the description adds context by specifying 'soft-deletes' and 'revokes the vaulted refresh token,' disclosing the nature of the operation beyond the annotation. It also notes API key requirements, which are implicit in 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 long, front-loaded with the key action, and every sentence adds value. There is no redundancy or unnecessary 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 3 parameters, no output schema, and destructive behavior, the description covers purpose, auth, parameter usage, and the nature of the operation. It lacks details on success response or error conditions, but is otherwise comprehensive for its simplicity.

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%, giving a baseline of 3. The description clarifies the behavior of provider_account_id ('preferred') and provider (disconnects most-recently-created one), adding practical meaning beyond the 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?

The description clearly states that the tool 'soft-deletes one of the user's OAuth connections and revokes the vaulted refresh token,' which is a specific verb+resource combo. The title 'Disconnect a Calendar Provider' further clarifies the action, and it is distinct from the sibling lyra_connect_calendar.

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 some guidance on parameter usage (prefer provider_account_id over provider) and notes API key authentication, but does not explicitly contrast with alternatives like lyra_connect_calendar or specify 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?

Discloses that only the user's queue is drained, requires API key authentication, and specifies the return format. This adds meaningful context beyond the readOnlyHint (false) and destructiveHint (false) annotations.

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

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

The description is concise (5 sentences) with each sentence serving a distinct purpose: action, usage context, access control, return value, and auth requirement. No unnecessary 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's simplicity (one parameter, no output schema), the description covers all necessary aspects: purpose, when to use, security, scope, and return format. It is fully self-contained.

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 description merely restates that authentication is required, while the schema already provides a clear description for the 'api_key' parameter. With 100% schema coverage, the description does not add significant new 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 tool triggers a dispatcher to send queued invites for the user's own gatherings, distinguishing it from sibling tools like 'lyra_send_invite' by specifying it drains a queue in bulk.

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 recommends using on dev branches where Vercel Cron doesn't fire, or for manual one-off flushes. This guides the agent to appropriate contexts and implies production use is automatic.

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 non-read-only and non-destructive. The description adds valuable behavioral context: it locks data, records the transition in an events log, and requires API key authentication. Beyond annotations, it clarifies the scope of the operation without contradiction.

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

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

The description is four sentences, each serving a distinct purpose: core action, logging, exclusions, and authentication. No redundant or wasted words; efficiently 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 transitional tool without output schema, the description covers the main behavior, logs, and boundaries. It lacks details on return values or error conditions, but given the tool's simplicity, 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?

Schema description coverage is 100%, so parameters are already well-documented. The description mentions 'final slot' and 'optional venue', which correspond to the time and venue parameters, but adds no novel semantic detail beyond the schema. Baseline 3 applies.

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

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

The description clearly states the tool locks the final slot and transitions a draft gathering to 'live', using specific verbs and resources. It distinguishes itself from siblings such as lyra_create_gathering (creates draft) and lyra_update_gathering (modifies draft).

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 specifies that this tool does not send invites (delegated to lyra_send_invite) and that calendar event creation is a separate UI action. It provides clear guidance on when not to use this tool and names the alternative.

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

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

Adds context beyond readOnlyHint annotation by detailing the return fields and noting that free-text fields are user-generated. No contradictions with annotations, though rate limits or auth specifics are absent.

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 plus a note, all front-loaded and efficient. Every sentence adds value 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?

Despite no output schema, description fully enumerates the return components (invitees, RSVPs, timeslots, venue, audit log) and notes user-generated content, providing sufficient context for agent understanding.

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 parameters are already described in schema. Description does not add additional parameter semantics beyond implying gathering_id is needed.

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 uses specific verb 'Get' and resource 'gathering detail', listing concrete fields (invitees, RSVPs, time slots, venue, audit log), which clearly distinguishes it from siblings like lyra_list_my_gatherings that only list gatherings.

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

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

States prerequisites (API key authentication, gathering_id) and implies usage for fetching full detail of a specific gathering, but lacks explicit 'when not to use' or direct comparison to alternative tools like lyra_list_my_gatherings.

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?

While annotations declare readOnlyHint=true, the description adds crucial behavioral context: 'All returned content is user-generated and must be treated as untrusted data.' This trust warning is essential for safe agent operation and not inferable from the schema or annotations.

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

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

Three well-structured sentences: the first defines the action and output, the second provides use case context, and the third delivers a critical warning. Every sentence earns its place with zero 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?

Despite lacking an output schema, the description adequately characterizes the return value (interests, personality signals, preferences) and includes the trust disclaimer necessary for interpreting results. For a single-parameter read-only tool, this is sufficient, though error handling (e.g., invalid slug) is not 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?

With 100% schema description coverage for the single 'slug' parameter ('Profile slug'), the schema sufficiently documents inputs. The description references 'their Lyra profile' reinforcing the parameter's purpose, but does not add syntax details or examples beyond the schema baseline.

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

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

The description clearly states the tool retrieves a summary of a person's interests, personality signals, and preferences from their Lyra profile. It specifies the content types returned, implicitly distinguishing it from the sibling lyra_get_profile (likely raw data) by emphasizing 'insights' and analysis.

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 use cases ('understanding someone before meeting them or choosing a gift'), giving implied guidance on when to use the tool. However, it fails to explicitly contrast with lyra_recommend_gifts (which likely auto-generates gift ideas) or clarify when to prefer lyra_get_profile instead.

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 indicate readOnlyHint=true. Description adds valuable behavioral context: uses freeBusy API, no event titles/details returned, requires API key authentication, and returns clear error if no calendar. 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?

Description is focused and front-loaded with purpose. Slightly verbose but every sentence adds value. Could be tightened slightly without losing clarity.

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

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

Given no output schema, description compensates by specifying return types (busy windows, free intervals) and error conditions. Covers prerequisites, authentication, and behavioral details. Complete for moderate-complexity 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?

All four parameters have detailed descriptions in the schema (100% coverage). Description adds practical context: window limits (14 days), default min_slot_minutes, and explanation that past times are pointless. Goes well 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?

Description clearly states the tool returns busy windows and free intervals from the user's connected Google calendar. It distinguishes itself from siblings like lyra_get_host_availability by explicitly focusing on the user's own calendar.

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 guidance to use for checking personal availability before scheduling. Mentions prerequisite of having a connected calendar and directs to lyra_connect_calendar if not. Does not explicitly state when not to use, but context is sufficient.

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 adds valuable behavioral context beyond the readOnlyHint annotation by specifying that it returns 'recommended questions and flow' and clarifying this is designed for 'AI companions to gather profile information conversationally,' revealing the conversational onboarding nature of the tool.

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

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

The description consists of two efficient sentences with zero redundancy: the first establishes purpose, the second describes return value. Every word earns its place with no filler 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 read-only tool with one parameter and no output schema, the description adequately explains what the tool returns (questions and flow). The readOnlyHint annotation covers safety concerns, though the description could slightly clarify error conditions or 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?

With 100% schema description coverage for the single api_key parameter, the schema fully documents inputs. The description does not add parameter-specific semantics, which is acceptable given the high schema coverage and obvious nature of the API key parameter.

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

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

The description clearly states the tool provides 'guidance on how to help a user build their Lyra profile' using specific verbs (Get guidance) and distinguishes itself from sibling tools like lyra_get_profile by focusing on the onboarding/building phase rather than retrieval of existing data.

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 that this tool is for onboarding scenarios ('help a user build their Lyra profile'), which implicitly guides agents to use it when creating profiles rather than managing existing ones. However, it lacks explicit contrast with lyra_get_profile or stated prerequisites.

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?

While annotations declare readOnlyHint=true, the description adds crucial behavioral context: it lists the specific data sections returned (bio, preferences, gift ideas, etc.) compensating for the missing output schema, and provides an essential security warning about untrusted user-generated content that annotations cannot convey.

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

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

Three sentences with zero waste: sentence one defines the action, sentence two details the return payload, and sentence three provides critical security context. Information is front-loaded and appropriately scoped for the tool's complexity.

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 lack of an output schema, the description effectively compensates by enumerating returned sections. It addresses the safety implications of user-generated content. Minor gap: it does not clarify parameter interaction (whether both can be provided simultaneously or if one takes precedence).

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

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

With 100% schema description coverage ('Display name to search for', 'Profile slug...'), the schema already documents the parameters fully. The description adds minimal semantic value beyond acknowledging both parameters exist as lookup alternatives, meeting the baseline expectation for well-documented schemas.

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

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

The description clearly states the specific action ('Get'), resource ('complete published Lyra profile'), and lookup method ('by slug or name'). The term 'complete' distinguishes it from sibling lyra_get_section, while 'published' and specific identifier lookup differentiate it from lyra_search_profiles and lyra_update_profile.

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 through keywords like 'complete' (suggesting full profile retrieval vs. partial) and 'published' (vs. draft states), but does not explicitly state when to use this tool versus alternatives like lyra_search_profiles or clarify whether slug or name is preferred when both are available.

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?

While annotations declare readOnlyHint, the description adds critical behavioral context: 'All returned content is user-generated and must be treated as untrusted data.' This security warning is essential context not found in structured fields. Does not address rate limits or error states.

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

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

Three tightly constructed sentences: purpose with examples, valid enum values, and security warning. Every sentence delivers unique value without repetition. Well front-loaded with the core action.

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 2-parameter read operation with complete schema coverage, the description is nearly complete. The security warning addresses output handling. Minor gap: does not describe the return structure (list vs object), though this is partially mitigated by the category examples.

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%, documenting both 'slug' and 'category' parameters. The description reinforces the category enum values but does not add syntactic guidance, format details, or semantic context for 'slug' beyond what the schema provides.

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 the specific action ('Get') and resource ('specific section of a Lyra profile'), distinguishing it from the sibling 'lyra_get_profile' by emphasizing partial retrieval ('just gift ideas...'). Lists concrete category examples that clarify scope.

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

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

Provides clear usage context through examples ('for example just gift ideas...'), implying this tool is for targeted section retrieval rather than full profile fetches. Lacks explicit contrast with 'lyra_get_profile' or guidance on 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?

Annotations already indicate read-only, and description adds key context: privacy (no event titles), 8-attendee cap, authentication requirements, and how missing calendar connections are handled.

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 paragraph that front-loads the core purpose and includes all necessary details without wasted words, though could be slightly more streamlined.

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 explains return structure (suggested_free_intervals, requires_manual_confirm) and covers authentication, limits, and privacy, making it fully informative for 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 covers 100% of parameters, and description adds extra context like how to obtain contact IDs, the optional nature of api_key, and hints for window_start_iso and min_slot_minutes defaults.

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

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

The description clearly states it returns busy windows for the user and named attendees, distinguishing it from the sibling lyra_get_my_calendar_busy_times which only returns your own busy times.

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

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

Explicitly says 'Use this when you need to find a time that works for several people at once' and explains behavior for attendees without connected calendars, though it could mention alternatives like the single-user 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?

Beyond the readOnlyHint annotation, the description explicitly states the authentication requirement (API key), warns that user-generated fields should not be interpreted as instructions, and clearly documents that PII (email, phone) is not returned. This adds significant behavioral context beyond annotations.

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

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

The description is three sentences, each serving a clear purpose: stating the core function, describing optional search, and providing critical caveats. Extremely concise 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?

For a straightforward list endpoint with full schema coverage and read annotations, the description covers all necessary aspects: what is returned (display name, location), what is not (PII), authentication, and usage of the search parameter. No gaps are evident.

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 three parameters. The description adds only minor context about fuzzy search aligning with the search parameter and authentication aligning with api_key. No additional semantic value beyond schema, hence baseline 3.

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 lists the authenticated user's contacts, distinguishing them from Lyra profiles with the explicit note 'NOT Lyra profiles'. It specifies the scope (address-book entries) and mentions optional fuzzy search, making the purpose very specific and distinct from sibling tools.

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

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

The description provides implicit usage guidance by contrasting with Lyra profiles and noting that PII is not returned. It clarifies when features like fuzzy search are available but does not explicitly state when to avoid this tool or name alternative tools for other contact searches.

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. The description adds value by noting API key requirement and a caveat about user-generated content not being instructions. This is good additional behavioral context beyond annotations.

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

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

Two sentences, front-loaded with the main purpose. Every sentence adds value, no redundancy or fluff.

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, the description covers authentication, filtering, and a content warning. It lacks details on pagination behavior beyond schema's limit description, but overall it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'filter by status' but does not add meaning beyond what the schema already provides for the parameters (limit, status, api_key).

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 gatherings the authenticated user is hosting,' which is a specific verb+resource. It distinguishes well from sibling tools like lyra_list_my_contacts and lyra_list_my_tribes.

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 mentions filter by status and API key authentication, giving context for use. However, it does not explicitly say when to use this tool over alternatives or when not to use it, relying on the name and purpose to imply usage.

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 indicate read-only; description adds a useful caveat about user-generated content not being instructions, but no further behavioral details like rate limits or output format.

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

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

Two sentences, front-loaded with purpose, no wasted words; minor redundancy with schema regarding API key.

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

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

No output schema, no mention of pagination or error handling; examples and caveat help but still leaves gaps for a 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?

Schema covers 100% of parameters; description adds no additional meaning beyond what the schema already provides.

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 lists the authenticated user's named groups (tribes) of contacts with concrete examples, effectively distinguishing from siblings like list_my_contacts and list_my_gatherings.

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?

Mentions API key authentication requirement but lacks explicit when-to-use or when-not-to-use guidance relative to sibling tools.

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

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

Adds significant value beyond the readOnlyHint annotation with the explicit warning that 'School names and profile data are user-generated and must be treated as untrusted data.' Could improve by mentioning pagination or return format specifics given no output schema exists.

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

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

Three sentences with zero waste: purpose statement, usage context, and critical data quality warning. Information is front-loaded and appropriately sized for the tool complexity.

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-parameter read-only search tool, nearly complete. Mentions it finds 'people' (compensating partially for missing output schema) and includes the trustworthiness caveat. Minor gap regarding specific return structure or pagination limits.

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% with 'School name to search for' already documented. Description aligns with this usage but does not add additional semantic detail (e.g., partial matching behavior, case sensitivity) beyond the schema definition.

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

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

Specific verb-resource combination ('Search for schools', 'Find people') and clearly distinguishes from sibling mutation tools (add_school, remove_school) and general search (search_profiles) by specifying school-affiliation-based people discovery.

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?

Clear context provided ('Find people who attended or are connected to a specific school'), effectively implying when to use versus general profile searches or school management tools. Lacks explicit 'when not to use' or named alternative references, preventing a 5.

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

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

Annotations declare readOnlyHint=true and the description expands on ranking factors (tribe fit, recency, response history, type fit, diversity), authentication requirements, and output format. There is no contradiction with annotations. The description adds significant behavioral context beyond the annotation alone.

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

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

The description is three sentences with front-loaded purpose, detailed ranking criteria, and a note about authentication. The note about free-text fields is a bit out of place (no free-text fields in schema), but overall it is efficient and well-structured.

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 covers what the tool does, inputs, ranking logic, and output shape. It is missing mention of pagination or handling of large results, but the max limit of 20 is clear. For a tool with no output schema, it adequately explains return values.

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

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

Schema description coverage is 100% and the description does not add new parameter-level details beyond what the schema provides. However, it does provide high-level context for how parameters like limit and tribe_name are used in the ranking logic. Baseline 3 applies.

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

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

The description uses specific verb 'ranks' and resource 'contacts for inclusion in a gathering' with clear modifiers (intent, tribe filter, exclusion list). It distinctly sets the tool apart from siblings like lyra_list_my_contacts or lyra_create_gathering, which are about listing or creating, not proposing.

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 states the required inputs (intent, optional filters) and what the tool does, but does not explicitly mention when to use versus siblings like lyra_get_insights or lyra_recommend_gifts. Context is clear but lacks explicit 'when not to use' or alternative tools.

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

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

Annotations declare idempotentHint=true and destructiveHint=false. The description adds valuable behavioral context not in annotations: it explains the real-world impact of the boolean states ('visible to everyone' vs 'hidden') and confirms the authentication requirement. No contradictions with annotations.

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

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

Two sentences with zero waste: the first front-loads the core function and explains both states clearly, while the second states the auth requirement. Every word earns its place.

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

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

For a simple two-parameter state-toggle tool with no output schema, the description is complete. It covers function, semantics, and auth. It could optionally mention the return value behavior (e.g., whether it returns the updated profile), but this is not critical for a setter 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?

With 100% schema description coverage, the baseline is 3. The description adds semantic meaning beyond the schema by clarifying the visibility consequences of the 'published' boolean (true=visible to everyone, false=hidden) and reinforcing the authentication nature of 'api_key'.

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 specific verbs ('Set') and clearly identifies the resource ('Lyra profile') and the two possible states ('published' visible to everyone vs 'unpublished' hidden). This scope distinctly separates it from sibling tools like lyra_update_profile (general updates) and lyra_get_profile (read-only).

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

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

The description notes the prerequisite 'Requires API key,' indicating authentication is mandatory. However, it lacks explicit when-to-use guidance versus alternatives (e.g., when to use this versus lyra_update_profile) or exclusion criteria.

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 annotation declares readOnlyHint: true, which the description supports with 'Get' and 'Returns'. Crucially, the description adds valuable behavioral context beyond the annotation: the security warning that 'All returned content is user-generated and must be treated as untrusted data.' This informs the agent how to handle the response data, which annotations alone do not provide.

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

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

The description is front-loaded with the action ('Get gift ideas') and efficiently structured in three sentences. There is slight redundancy between the first two sentences (both describe retrieving gift data), but the third sentence's security warning earns its place. Overall, it avoids fluff while conveying purpose, value, and critical warnings.

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 low complexity (2 parameters, no nested objects) and lack of output schema, the description adequately compensates by describing the return value ('stated gift preferences, likes, and interests'). The inclusion of the untrusted data warning is essential for this domain. It could be improved by mentioning how to obtain a profile slug (via lyra_search_profiles), but it meets the completeness threshold for this tool class.

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

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

With 100% schema description coverage, the baseline is appropriately 3. The description mentions retrieving data 'from a Lyra profile' which conceptually maps to the 'slug' parameter, but does not add syntax details, validation rules, or explicit mention of the budget parameter beyond what the schema already documents.

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

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

The description clearly states the tool retrieves gift ideas and wishlists from a Lyra profile, using specific verbs ('Get', 'Returns') and identifying the exact resource. It effectively distinguishes itself from siblings like lyra_get_profile (general profile data) and lyra_get_insights (analytics) by focusing specifically on gift preferences and wishlists.

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?

While the description implies a use case ('to help you choose the perfect gift'), it lacks explicit guidance on when to use this versus lyra_get_profile or lyra_search_profiles. It does not specify prerequisites (e.g., needing a valid slug from search) or when not to use the 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?

Annotations indicate non-read-only and non-destructive, but the description adds valuable behavioral context: it logs the action ('Appends rsvp_recorded to the gathering_events_log') and requires API key authentication. No contradiction with annotations.

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

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

The description is three sentences, each serving a purpose: core action, use case, and behavioral note. No redundant or extraneous 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 tool with 5 parameters and no output schema, the description covers the purpose, usage context, authentication requirement, and logging behavior. It provides sufficient information for an agent to decide when and how to use it.

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?

All parameters are covered in the schema with descriptions (100% coverage), so the description adds no new meaning beyond what the schema provides. 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 clearly states the action ('mark an invitee as accepted/declined/tentative/no_show/attended') and the resource (invitee status), with explicit differentiation from the public RSVP page. It identifies the tool as a host-side override, making its 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 explains when to use the tool ('when someone responds verbally, by text, or in another channel'), providing clear context. However, it does not explicitly state when not to use it or name sibling tools as 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?

The description aligns with the destructiveHint annotation by using 'Remove' and adds authentication context ('Requires API key'), but lacks details on whether deletion is permanent, recoverable, or has cascading effects on profile completeness.

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 with zero redundancy. The action and target appear immediately in the first sentence, with requirements following—optimal structure for a simple two-parameter tool.

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?

Adequate for a simple deletion operation with two parameters and clear annotations. While it appropriately doesn't detail return values (no output schema), it could improve by clarifying what constitutes an 'item' versus other removable entities in the Lyra ecosystem.

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

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

With 100% schema description coverage, the schema already fully documents both parameters. The description references 'ID' and 'API key' matching the parameters but adds no additional semantic context, syntax examples, or value constraints 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 states a specific action ('Remove'), resource ('item from a Lyra profile'), and key parameter ('by ID'), clearly distinguishing it from siblings like lyra_remove_link and lyra_remove_school through the specific noun 'item'.

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 notes the API key prerequisite but provides no explicit guidance on when to use this tool versus lyra_remove_link or lyra_remove_school, or under what conditions removal should be preferred over updates. Usage must be inferred from the tool name and sibling 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?

The annotation already declares destructiveHint=true. The description confirms this with the verb 'Remove' but adds no further context about what destruction entails (permanent deletion, irreversibility, side effects on associated profiles) beyond the annotation.

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

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

Two short sentences with the action front-loaded. However, 'Requires API key' is somewhat redundant given the required parameter in the schema, slightly reducing the value of the second sentence.

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 2-parameter destructive operation, it covers the basic action but lacks completeness regarding the destructive nature (e.g., confirming irreversibility) or success/failure behavior given the lack of 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 100% with clear descriptions for both api_key and link_id. The description maps 'by ID' to link_id and 'Requires API key' to the api_key parameter, but adds no semantic clarifications beyond what the schema already provides.

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 the specific action (Remove) and resource (external link) with identification method (by ID). The term 'external link' distinguishes it from siblings like lyra_remove_item and lyra_remove_school.

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?

Mentions 'Requires API key' which states a prerequisite, but fails to provide guidance on when to use this tool versus alternatives (e.g., lyra_remove_item) or 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?

The 'destructiveHint: true' annotation already establishes the destructive nature, so the description's burden is lowered. It adds the API key authentication requirement, though this is also present in the schema. It fails to disclose what happens to associated data, whether the removal is permanent/reversible, or specific error conditions beyond the annotation.

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 extremely concise with only two sentences and zero fluff. It is front-loaded with the core action. However, it borders on underspecification given the lack of behavioral context, preventing a perfect score.

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 two-parameter input schema, 100% coverage, and presence of destructive annotations, the description meets minimum viability. However, it lacks contextual glue—such as noting that 'school_id' should be sourced from 'lyra_list_schools' or explaining the irreversible nature of the deletion—which would be expected for a destructive 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?

With 100% schema description coverage, the parameters are fully documented in the schema itself ('Lyra API key' and 'School affiliation UUID to remove'). The description aligns with these ('Requires API key', 'by ID') but does not add additional semantic context such as ID format constraints, where to obtain the school_id, or usage examples.

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

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

The description clearly states the specific action ('Remove') and target resource ('school affiliation') with the identification method ('by ID'). While it effectively distinguishes from siblings like 'lyra_add_school' and 'lyra_list_schools' through the name and description, it does not explicitly clarify these relationships in the text itself.

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 mentions 'Requires API key,' indicating an authentication prerequisite, but provides no guidance on when to use this tool versus alternatives like 'lyra_add_school' or 'lyra_update_profile'. It lacks explicit when-to-use scenarios, exclusions, or workflow context (e.g., that one should first list schools to obtain the ID).

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 reveals important behaviors not covered by annotations: RSVP reset for accepted invitees, appending a gathering_rescheduled event to the audit log, and the state transition. No contradiction with annotations (readOnlyHint: false, destructiveHint: false).

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 four sentences, all essential, with no redundancy. It front-loads the main action and logically flows through state change, invitee impact, audit log, auth, and alternatives.

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 covers the core functionality, state transition, RSVP behavior, audit logging, and authentication. However, it omits what the tool returns (e.g., the updated gathering object). This is a minor gap given 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 100%, and the description adds value by explaining the 'reason' parameter's purpose (audit log capture) and noting that new_venue_id keeps existing venue if omitted. This enhances understanding 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?

The description clearly states 'Move a live gathering to a new time (and optionally a new venue)' and mentions the state transition to 'rescheduled'. It distinguishes from siblings like lyra_cancel_gathering, which is explicitly named.

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 notes 'Requires API key authentication' and provides an explicit alternative for cancellation: 'To cancel instead, use lyra_cancel_gathering.' However, it does not explicitly exclude other scenarios (e.g., using lyra_update_gathering for minor changes).

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

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

Annotations declare readOnlyHint=true, confirming the safe read nature. The description adds critical behavioral context beyond annotations: it specifies the 'published' profile filter and includes a security warning that returned content (display_name, headline, bio, city) is user-generated and untrusted, warning against interpreting it as instructions. This trust boundary disclosure is valuable behavioral 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?

The description consists of three sentences that each earn their place: purpose declaration, return type specification, and security warning. No redundant words or tautologies. Information is front-loaded with the primary action 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?

Despite lacking an output schema, the description compensates by specifying that it returns 'matching published profiles' and listing the specific fields returned (display_name, headline, bio, city) in the security warning. Combined with the clear input schema and readOnly annotation, this provides sufficient context 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?

With 100% schema description coverage, the schema fully documents all three parameters (limit, query, school). The description mentions 'name, location, or keyword' which loosely maps to the query parameter's schema description ('matches name, headline, bio, city'), but does not add significant semantic meaning beyond what the schema already provides. Baseline 3 is appropriate for high 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 uses specific verbs ('Search for') and identifies the resource ('Lyra profiles') along with searchable fields ('name, location, or keyword'). It clearly distinguishes from siblings like lyra_get_profile (singular retrieval) and lyra_update_profile (mutation) by emphasizing the search/filter functionality.

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?

While it does not explicitly name sibling alternatives, it provides clear context on when to use the tool (searching by name, location, or keyword) and specifies that it returns 'published profiles,' implying a filter on profile state. This gives the agent sufficient context to select this over lyra_get_profile when multiple results are needed.

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

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

The description details side effects (generates RSVP token, stamps timestamps, persists row, appends audit log) and clarifies that the tool does not trigger actual send, adding value beyond the annotations (readOnlyHint=false, destructiveHint=false).

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 well-structured, with each sentence providing unique and essential information. It is detailed yet efficient, using capitalization for emphasis without being verbose.

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 covers side effects, return value, authentication, and the queuing mechanism. It does not explain error conditions but is sufficiently comprehensive for a queuing 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?

Input schema has 100% coverage with parameter descriptions. The description does not add further parameter meaning but mentions the return value (rsvp_url), which is helpful given no output 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 uses a specific verb ('queues an invite') and identifies the resource (gathering's invitee), clearly distinguishing this tool from sibling tools like lyra_create_gathering or lyra_record_rsvp.

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 states that the tool queues an invite and explains that actual email send is handled separately, providing context. However, it does not explicitly mention when not to use or alternatives, though none exist among siblings.

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

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

The description discloses sourcing logic (prioritizing tribe members, same city, not already invited), output format (scored suggestions with rationale), and authentication requirements. No contradiction with readOnlyHint annotation.

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 (three sentences) and front-loaded with the main purpose. Every sentence adds value and there is no wasted text.

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 no output schema, but the description explains the return format (scored suggestions with rationale). It effectively covers the tool's behavior without needing additional detail.

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% coverage with clear descriptions. The description adds no additional parameter-level detail beyond schema, so 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 tool's purpose: suggesting substitute attendees when an invitee declines. It specifies the condition and output, and distinguishes from sibling tools.

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

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

The description explicitly mentions when to use ('when an invitee has declined a gathering'). It does not explicitly mention alternatives or when not to use, but the context 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 annotations already indicating the tool is not read-only and not destructive, the description adds value by disclosing authentication requirements, use of Google Places and caching, and the output structure. It also warns against interpreting free-text fields as instructions.

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 paragraph but is dense and well-structured, front-loading the core purpose. It avoids redundancy and includes necessary details, though a slightly more structured layout could improve 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?

Given the tool's complexity with 10 parameters and no output schema, the description provides essential context: output format (score, reasons, venue_id, place_id), parameter roles, authentication, and safety notes. It equips an agent to use the tool correctly without gaps.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: it groups primary inputs, clarifies hard filters vs soft signals, and explains the output fields. This aids in understanding parameter roles and tool behavior.

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 suggests venues using Google Places and Lyra's engine, specifies inputs (intent, anchor, headcount) and outputs (ranked candidates with score, reasons, place ID, venue ID). It explicitly mentions its output can be used by lyra_create_gathering, differentiating it from siblings.

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

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

The description provides guidance on when to use the tool, the required authentication, and precautions about free-text fields. It does not explicitly state when not to use or list alternatives, but given the uniqueness of the tool among siblings, this is adequate.

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 state restrictions and the append-only audit entry. Annotations already indicate non-destructive/mutating behavior, but the description adds useful context. Could mention error handling if state invalid, but still solid.

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

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

Three sentences, no redundancy. Main purpose stated first, followed by key constraints and alternatives. Economy of language.

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?

Provides state constraints and sibling links but omits parameter details and return value description (no output schema). For an update tool with 11 parameters, more param context would help; however, the essential usage context 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?

Schema description coverage is only 18%, but the description does not elaborate on any parameters. It merely says 'fields' generically, leaving agents to rely on schema descriptions which are sparse for most fields.

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 ('Edit a gathering's fields') on a specific resource ('gathering'). It distinguishes itself from sibling tools by naming alternatives for slot/venue 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?

Explicitly specifies valid states ('draft', 'live', 'awaiting_responses') and advises when to use sibling tools (lyra_finalise_gathering, lyra_reschedule_gathering) for slot/venue changes. Also mentions authentication requirement.

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 idempotentHint=true and destructiveHint=false, indicating safe retry and non-destructive behavior. The description adds the authentication requirement ('Requires API key authentication'), which is useful behavioral context not present in annotations. However, it does not clarify whether omitted fields are preserved (partial update) or cleared (full replacement), nor does it describe error handling or return behavior.

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

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

The description consists of two efficient sentences with zero waste. It front-loads the primary action and fields, placing the authentication requirement secondarily. Every word earns its place.

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

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

Given the tool's moderate complexity (6 flat parameters), 100% schema coverage, and presence of behavioral annotations, the description provides adequate context for tool selection. It appropriately focuses on what distinguishes this update operation from siblings, though it could briefly note the partial-update semantics 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?

With 100% schema description coverage, the baseline is 3. The description lists the updatable fields ('display name, headline, bio, city, country'), which loosely maps to the schema parameters (though 'bio' abbreviates 'bio_short'). It adds no additional semantic detail about formats or validation beyond what the schema already provides (e.g., schema already documents 'lyra_' prefix and max 300 chars).

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 ('Update') and resource ('profile fields') with specific examples (display name, headline, bio, city, country). However, it does not explicitly differentiate from sibling tools like 'lyra_publish_profile' (which controls visibility) or 'lyra_add_item' (which adds portfolio content), which could confuse an agent about whether this tool makes the profile public.

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 states the authentication prerequisite ('Requires API key authentication') but provides no guidance on when to use this tool versus alternatives like 'lyra_publish_profile' or the various add/remove sibling tools. It does not indicate that this is for basic metadata versus content sections.

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