Crystals MCP Server by RoxyAPI

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds valuable behavior: pagination is supported, results are minimal summary fields, and a separate detail endpoint exists. This goes beyond the annotations by explaining the response scope and the existence of an alternative for richer data.

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 earning its place: the first states the action and filters, the second clarifies the response shape and points to the detail endpoint, and the third gives concrete use cases. It is front-loaded with the key information and avoids 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?

Given no output schema, the description adequately explains the tool's scope of returning 'minimal summary fields' and directs to the detail endpoint for more. The pagination and filter capabilities are stated, and the rich input schema fills in parameter details. Some specifics about response shape (e.g., list vs object) are missing, but the core usage context is complete.

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

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

The input schema covers all 9 parameters with detailed descriptions, enums, defaults, and valid values. The description only lists the filter dimensions (chakra, zodiac, element, color, planet) which are already fully documented in the schema. It doesn't add extra semantics such as how filters combine or pagination parameter usage, so it meets the baseline but doesn't elevate above 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 uses a specific verb ('Retrieve') with a clear resource ('healing crystals and gemstones') and states the core capability: listing with pagination and optional filters. It distinguishes itself from sibling tools by covering the general list endpoint and explicitly pointing to a 'detail endpoint' for full healing properties, unlike the specialized filter 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 clear context for when to use the tool: for listing crystals with pagination and filters, and for building explorer/guide apps. It also directs users away for full healing properties ('Use the detail endpoint'), though it does not explicitly name sibling tools or state exclusions. This is more than implied usage but lacks explicit when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns 'summary data', references GIA-authoritative assignments, and implies the tool is read-only by design. No contradiction exists between description and 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 long and front-loaded with the primary action and resource. Each sentence earns its place: purpose, pointer to more detailed data, and example use cases. No redundant repetition of schema fields.

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, the fully documented schema, and the annotations, the description is complete enough. It explains the data scope (birthstone summary), the authoritative basis (GIA), and the alternative endpoint for richer details. Without an output schema, enumerating summary fields might be helpful but is not critical for this lightweight lookup.

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

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

The schema description coverage is 100%, with month, lang, and compact all clearly documented in the input schema. The description adds no new parameter-level semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Get') with a clear resource ('traditional birthstone crystals for a given birth month'), making the tool's scope immediately obvious. This clearly distinguishes it from sibling tools focused on chakra, colors, elements, zodiac signs, and planets.

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 by naming practical use cases ('birthday gift recommendations') and directs users to the '/crystals/:id detail endpoint' when full healing properties are needed. It does not explicitly name sibling tools as alternatives, but the guidance is sufficient for typical selection scenarios.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds that it 'Returns summary data for each crystal' while directing users to the detail endpoint for full properties. This sets expectations about the response depth, though pagination and compact behavior are not mentioned in the description.

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 with no fluff: it states the action, notes the summary output, provides a pointer to the detail endpoint, and lists supported chakras and use cases. Every sentence earns its place and the structure is well 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?

This is a read-only filtered-list tool with a rich schema (5 params, 100% coverage) and safe annotations, so the description is somewhat complete. It communicates the summary nature of results and the availability of a detail endpoint, but it does not specify the exact response shape or pagination behavior, leaving some room for interpretation.

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

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

Schema coverage is 100% with clear descriptions for all 5 parameters, so the baseline is 3. The description adds no parameter-level meaning beyond restating the chakra enum, and it does not elaborate on lang, limit, offset, or compact behavior 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?

The description uses a specific verb 'Get' and identifies a precise resource: 'healing crystals and gemstones that resonate with a specific chakra energy center.' It clearly distinguishes this tool from sibling tools by focusing on chakra filtering, and it enumerates all 7 supported chakras, leaving no ambiguity.

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

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

The description provides clear usage context by stating the tool is 'Essential for crystal grid building, chakra balancing, and energy healing applications.' It also implicitly contrasts with the detail endpoint by pointing to '/crystals/:id' for full healing properties, but it does not explicitly name sibling tools or state when not to use this tool.

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

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

The description aligns with annotations (readOnlyHint=true, destructiveHint=false) by indicating a read-only list operation. It adds context about uniqueness and applicability to the color filter, but doesn't disclose many behavioral details beyond that (e.g., ordering, errors), which is acceptable for a simple read-only endpoint.

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

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

The description is two sentences, with the primary action in the first sentence and additional usage context in the second. 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?

As a simple, parameterless-required reference endpoint without an output schema, this description covers the purpose, return kind (list of unique colors), and primary use case. It's sufficiently complete for an AI agent to choose and invoke it correctly.

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

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

The schema fully describes the only parameter `compact` with a clear explanation of its effects. The description doesn't add parameter information, but with 100% schema coverage, the baseline score of 3 applies.

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

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

The description clearly states the tool's function with a specific verb ('List all unique crystal colors') and explicitly distinguishes it from sibling tools by focusing on the color facet and connecting it to the GET /crystals color filter.

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

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

It provides clear context for when to use this endpoint: to obtain color values for filtering crystals, and mentions use cases like building color-based browsing and pickers. It doesn't explicitly name alternatives, but sibling names make it clear that other facet tools exist for other filters.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds behavioral value by explicitly stating the tool 'Returns summary data for each crystal' and pointing to the detail endpoint for comprehensive data, helping the agent manage expectations about response depth. It doesn't report rate limits or pagination internals, but the annotations cover mutation risks.

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 wasted words. The first sentence front-loads the action and scope, the second provides a pointer for deeper data, and the third lists use cases. It is compact and scannable for an AI agent.

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

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

Given the absence of an output schema, the description reasonably covers the return nature with 'summary data' and the fallback to the detail endpoint. The context signals indicate a well-documented input schema and read-only annotations, so the description doesn't need to explain every parameter. It could mention pagination or count behavior, but the schema already describes those. Overall, it is sufficiently complete for this tool's complexity.

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

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

With 100% schema description coverage, the baseline is a 3. The description reiterates the supported five elements, which is slightly redundant with the enum, and does not add meaningful new semantics beyond the schema. The term 'summary data' hints at response character, but it's not parameter-specific. Thus, it aligns with the baseline without notable compensation.

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

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

The description opens with a specific verb 'Get' and identifies the resource 'healing crystals and gemstones' plus the scope 'associated with a specific natural element.' It clearly distinguishes itself from sibling tools by focusing on element-based filtering, avoiding ambiguity.

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

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

It provides explicit guidance by directing users to the '/crystals/:id detail endpoint' for full healing properties, which functionally contrasts with this summary-level tool. It also names concrete use cases: 'elemental crystal selection, nature-based healing, and element-themed crystal grid applications.' While it doesn't explicitly exclude other siblings like chakra or zodiac, the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds value by specifying the detailed content scope (healing interpretations, chakra associations, zodiac, elemental properties, pairings) and claims authoritative coverage, which informs the agent about response richness. 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 concise sentences: purpose, content list, and authority claim. Each sentence contributes unique information, the description is front-loaded, and there is no fluff or redundancy.

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

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

For a simple single-crystal lookup with no output schema, the description sufficiently covers what the tool does and what data it returns. It does not need to explain return shape or error handling, and the schema already covers parameter details. The description is complete for this tool complexity.

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

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

Schema coverage is 100% with all parameters described (id, lang, compact), so the description does not need to compensate. The phrase 'specific crystal' aligns with the id parameter but adds no additional syntax or format details 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?

The description clearly states the purpose with a specific verb 'Get' and resource 'specific crystal or gemstone', and enumerates the exact data types returned (spiritual, emotional, physical, chakra, zodiac, elements, pairings). This distinguishes it from sibling tools that focus on single attributes like chakra or colors.

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

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

The description implies usage for a known crystal by ID, but it does not explicitly mention when to use this tool versus alternatives like get_crystals_search or get_crystals_random, nor does it provide exclusions. The context is clear but lacks explicit alternative guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds return-content detail ('Returns the source crystal along with its recommended companion stones and their properties'), which is useful beyond annotations. It does not disclose other behavioral traits like error handling or limits, but with annotations present, this is acceptable.

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

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

Two sentences deliver purpose, return details, and use cases without redundancy. Every sentence contributes, and the most important information is front-loaded.

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

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

Given the tool's simple structure (one required param, two optional with schema defaults), the description covers purpose, return content, and use cases. Annotations cover safety. It doesn't discuss pagination or errors, but that's acceptable for this tool scope.

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 fully documented in the schema (100% coverage), so the description need not add param semantics. It mentions 'given crystal' aligning with the required 'id' parameter, but adds no new syntax or format details. 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?

Description opens with 'Get crystals that pair well with a given crystal,' a specific verb+resource with clear scope. This distinguishes the tool from siblings like get_crystals_chakra or get_crystals_colors, which target different attributes.

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 'Essential for crystal grid building, healing combination recommendations, and crystal shop cross-sell features,' giving clear context for when to use. However, it does not explicitly call out alternatives or negative use cases, so not a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds minor behavioral context such as 'unique' and 'available', but does not go beyond annotations with details like pagination, limits, or error 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?

Three sentences deliver the purpose, usage, and target audience without any filler. The core action is front-loaded, and each sentence earns its place.

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

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

For a simple list endpoint with no required parameters, the description covers what the tool does, why it exists, and how to use its output. It lacks a precise return-shape statement, but the annotation and schema coverage make it adequately complete.

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

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

The compact parameter is fully described in the input schema, including behavior and token savings. With 100% schema coverage, the description does not need to add parameter details and does not, so a 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 starts with a specific verb and resource: 'List all unique planetary associations available in the database.' It clearly distinguishes itself from sibling tools by focusing on planetary associations and explicitly frames itself as an essential reference endpoint.

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

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

It explicitly instructs the agent to 'Use these values with the planet filter on GET /crystals,' giving clear context for when to invoke the tool. However, it does not name or exclude alternative tools, so it has clear context but no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds the key behavioral trait of non-determinism ('Returns a different crystal on each request'). It also frames this as a 'teaser', implying partial data. This goes beyond annotations without contradicting them.

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

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

Three sentences deliver the core purpose, key behavior, use cases, and alternative endpoints with no fluff. It is front-loaded with the primary action, and every sentence adds distinct value.

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

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

For a simple random-pick tool with no required parameters, rich schema descriptions, and safety annotations, the description covers the essential context: randomness, teaser nature, and how to get more complete data. It is fully sufficient for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100% for both parameters (lang and compact), so the schema carries the full semantic load. The description does not add any additional parameter meaning, which aligns with the baseline of 3 when schema already covers parameters thoroughly.

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

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

The description clearly states the tool gets a randomly selected healing crystal as a discovery teaser. It uses a specific verb ('Get') and resource ('healing crystal') while noting non-determinism, which distinguishes it from sibling tools like get_crystals_id or get_crystals_daily. The scope is immediately understandable.

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

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

The description explicitly tells when to use this tool for crystal discovery features, surprise picks, roulette games, and widgets. It also provides clear alternatives: use /crystals/:id for full healing properties and /daily for a deterministic daily crystal, giving strong contextual guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds behavioral context by stating that it 'returns summary data for each crystal' and by specifying the fields that are matched, which goes beyond the annotation baseline without contradicting 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?

The description is succinct and front-loaded with the core action in the first sentence. Each subsequent sentence adds useful context (return summary, alternative detail endpoint, use cases), though the final 'Useful for...' sentence is somewhat optional and could be trimmed without loss of essential meaning.

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

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

Given the tool's moderate complexity, the description provides adequate context alongside a rich schema and annotations. It covers return type, matching fields, a pointer to the detail endpoint, and example use cases. It does not mention pagination or compact output, but those are thoroughly documented in the schema, so the description is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description's mention of matching against 'crystal names, healing keywords, descriptions, and spiritual/emotional/physical meaning fields' largely mirrors the q parameter's schema description, adding little new semantic value. It does not augment the other parameters (lang, limit, offset, compact), which the schema already documents.

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

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

The description opens with a specific action and resource: 'Search for healing crystals by keyword or name.' It clearly defines the matching scope across multiple fields, distinguishing this keyword-search tool from structured-attribute sibling tools such as get_crystals_birthstone_month or get_crystals_chakra.

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

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

It provides context for when to use the tool (e.g., building crystal search bars and keyword-based recommendation features) and explicitly directs users to the /crystals/:id detail endpoint for full healing properties. However, it does not explicitly state when to prefer sibling tools that filter by structured attributes like chakra or zodiac sign, so it stops short of a fully explicit exclusion list.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the boundary that it returns only summary data, not full healing properties, which is valuable beyond annotations. It doesn't disclose rate limits, authorization, or other behavioral traits, but with safe read-only annotations, the lack of those is not critical. This is a moderate addition, hence a 3.

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 long and front-loaded with the core purpose. Sentence two guides users to an alternative for full details, and sentence three reinforces the supported scope. There is no filler, and every sentence contributes value.

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

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

With no output schema, the description hints at what is returned ('summary data') and what is not (full healing properties), which is helpful. It doesn't detail pagination or compact mode, but those are well-covered in the schema. For a read-only list tool with robust schema coverage, the description is mostly complete, but could be slightly more explicit about response shape (e.g., 'returns an array of crystals with name and properties'). Thus a 4.

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 every parameter (sign, lang, limit, offset, compact) having a description, enum, default, or example. The description itself does not add parameter-specific meaning beyond what the schema already provides. Per the baseline rule for high coverage, a 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: 'Get healing crystals and gemstones associated with a specific zodiac sign.' It uses a specific verb ('Get') and resource ('crystals and gemstones associated with a zodiac sign'), which distinguishes it from sibling tools like get_crystals or get_crystals_chakra. It also clarifies that it returns summary data, reinforcing its role as a zodiac-focused list tool.

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

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

The description gives explicit guidance: 'Use the /crystals/:id detail endpoint for full healing properties.' This points to a specific alternative (likely get_crystals_id) for a different use case. It also notes that the tool supports all 12 zodiac signs, implying it is the go-to for zodiac-based recommendations. However, it doesn't mention when to avoid it relative to other siblings like get_crystals_search or get_crystals_random, so it's not fully comprehensive.

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 convey safety (readOnlyHint=true, destructiveHint=false), lowering the bar. The description adds meaningful behavioral context: deterministic results based on date, consistency across users for a given day, and the 'teaser' nature. It also implies limited data by pointing to the detail endpoint for full properties. 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?

The description is three sentences, front-loaded with the core action, and each sentence earns its place: purpose, determinism/use cases, and alternative endpoint. Slightly wordy with the use-case list but remains efficient and focused.

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 (4 optional params, read-only, no output schema) and rich schema/annotations, the description covers the essential context: what it returns, determinism, and where to get full details. It doesn't describe the exact return shape, but as a 'teaser' this is acceptable and the compact parameter hints at data 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?

Schema description coverage is 100%, so the baseline is 3. The description mentions 'provided seed date' which relates to the 'date' parameter, and 'deterministic crystal' indirectly references 'seed', but it adds little beyond the schema's own detailed parameter descriptions. The schema already explains format, defaults, and behavior for all four parameters.

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: 'Get the crystal of the day as a discovery teaser.' It specifies the deterministic behavior based on date/seed, distinguishing it from random or search siblings. The phrase 'discovery teaser' and reference to the detail endpoint for complete properties further clarify its scoped role.

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 explicit when-to-use guidance: 'Perfect for daily guidance features, push notifications, wellness app widgets, and crystal journal integrations.' It also gives a clear alternative: 'Use the /crystals/:id detail endpoint for complete spiritual, emotional, and physical healing properties,' indicating when not to use this tool. This meets the criteria for explicit alternatives.

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