Prometheus MCP

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

With no annotations provided, the description carries the full burden of behavioral disclosure. While 'Add' implies mutation, the description fails to clarify idempotency (what happens if the guide is already in the collection), reversibility, side effects, or success/failure 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?

While brief at 5 words, the description is inappropriately sized for a 4-parameter mutation tool with no output schema. The single sentence is tautological and fails to earn its place by providing actionable context beyond the function name.

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 mutation tool with 4 parameters, zero annotations, and no output schema, the description is inadequate. It omits error handling, return value description, and operational constraints that would be necessary for safe 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?

The input schema has 100% description coverage (note, guide, order, collection all documented), establishing a baseline of 3. The description itself adds no parameter semantics, but the schema compensates adequately.

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

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

The description 'Add a guide to a collection' is a tautology that restates the function name (collections_add_guide) without adding specificity. While grammatically clear, it fails to distinguish from siblings like collections_remove_guide or explain scope beyond the obvious.

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

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

No guidance provided on when to use this tool versus alternatives like collections_remove_guide, or prerequisites such as whether the collection must exist first. The description offers no 'when-to-use' or 'when-not-to-use' 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?

With no annotations provided, the description carries the full burden of behavioral disclosure but provides minimal information. It does not address idempotency, error conditions (e.g., duplicate names), what data is returned, or side effects beyond the implied creation.

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?

While brief at only four words, this represents under-specification rather than efficient conciseness. The single sentence fails to earn its place by providing actionable context beyond the tool name itself.

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 mutation tool with no output schema and no annotations, the description is inadequate. It omits expected return values, error scenarios, and behavioral constraints that an agent needs to 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%, with all four parameters (name, tags, isPublic, description) adequately documented in the schema. The description adds no parameter-specific guidance, but the baseline score of 3 is appropriate when the schema does the heavy lifting.

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 'Create a new collection' is a tautology that restates the tool name (collections_create) without adding specificity. It fails to distinguish this tool from sibling operations like collections_add_guide or clarify what distinguishes a 'collection' from other entities.

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

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

No guidance provided on when to use this tool versus alternatives. Missing prerequisites (e.g., uniqueness constraints on names) and no mention of the relationship to collections_add_guide (which requires an existing collection).

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'Delete' implies destruction, the description omits whether this operation is permanent, whether it cascades to delete guides within the collection, or required permissions. Inadequate for a destructive 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 brief at three words. While not verbose, it is underspecified rather than efficiently concise. The single sentence does not earn its place by adding value beyond the tool name, though it is front-loaded with the action verb.

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 this is a destructive operation with potential confusion against collections_remove_guide and no annotations or output schema, the description is incomplete. It lacks safety warnings, cascade behavior details, or return value information necessary for safe 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 coverage is 100% (the 'slug' parameter is fully documented in the schema). The description adds no additional context about the parameter format or constraints, but the baseline score applies since the schema is self-documenting.

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 'Delete a collection' restates the tool name (collections_delete) with minimal expansion. It identifies the verb and resource but fails to distinguish scope or differentiate from sibling tools like collections_remove_guide.

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 no guidance on when to use this tool versus alternatives. Critically fails to clarify the difference between deleting an entire collection (destructive) versus removing a guide from a collection (collections_remove_guide). No prerequisites or warnings provided.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds valuable context that this operation includes nested guide data ('including all guides'), but fails to mention error handling (e.g., slug not found), authentication requirements, or whether this is a read-only operation.

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

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

The description is a single, efficient sentence that front-loads the action ('Get') and wastes no words. Every phrase earns its place: 'full details' signals completeness, and 'including all guides' clarifies the nested data return.

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 (one required parameter, no nested input objects) and lack of output schema, the description provides minimum viable context by indicating the return includes guide data. However, it could better compensate for the missing output schema by describing the structure or key fields of the returned collection object.

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 ('The collection slug'), establishing a baseline of 3. The description implies the slug identifies a specific collection but adds no further semantic value regarding format, validation rules, or example values 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 resource ('collection'), and clarifies scope with 'full details' and 'including all guides.' This implicitly distinguishes it from sibling tools like collections_list (which lists collections) and guides_get (which retrieves individual guides), though explicit differentiation would strengthen it further.

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 no guidance on when to use this tool versus alternatives like collections_list or guides_get. It omits prerequisites (e.g., whether the slug must be obtained first via collections_list) and gives no exclusions or conditional usage advice.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure but fails to explain what 'mine' and 'public' imply (ownership models), default behavior when filters are omitted, pagination, or return format. It merely repeats filter values available 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 consists of two efficient sentences with zero waste. The primary action is front-loaded in the first sentence, while the second sentence immediately clarifies optional filtering capabilities.

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 low complexity (2 optional string parameters) and complete schema coverage, the description is minimally viable. However, it lacks output specification (no output schema exists) and does not clarify the relationship between the 'filter' parameter values and the 'userName' parameter.

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

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

Input schema has 100% description coverage, documenting both 'filter' and 'userName' parameters. The description adds the word 'Optionally' and groups the filtering concepts, but provides no additional semantic context (e.g., username format requirements) beyond what the schema already states.

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

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

The description clearly states the verb 'List' and resource 'collections', establishing the core function. However, it does not explicitly differentiate from sibling tool 'collections_get', which likely retrieves a single collection versus this tool's list function.

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 available filters but provides no guidance on when to use this tool versus alternatives like 'collections_get' or 'guides_search'. It lacks explicit prerequisites, exclusions, or scenarios for optimal use.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It fails to clarify whether this operation deletes the guide entity or merely removes the association (unlinks), nor does it mention permission requirements, reversibility, or side effects on the collection's metadata.

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 six words. While efficiently front-loaded, the brevity contributes to gaps in behavioral transparency and usage guidelines. No redundant or wasted text, but insufficient length for the complexity of a mutation operation.

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 low complexity (2 parameters, no nesting) and complete schema coverage, the description is minimally adequate for invocation. However, for a mutative operation with no output schema and no annotations, it lacks critical context about the operation's scope and safety.

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

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

Schema description coverage is 100%, with both 'collection' and 'guide' slugs documented in the schema. The description adds no additional semantic context (e.g., slug format, validation rules, examples), meeting the baseline for high-coverage 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 uses a specific verb ('Remove') and identifies the exact resources involved ('guide', 'collection'). The phrasing 'from a collection' implicitly distinguishes this from collections_delete (which deletes the collection itself), though it does not explicitly clarify whether the guide entity survives the operation.

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

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

No guidance provided on when to use this tool versus siblings like collections_add_guide (inverse operation) or collections_delete (collection removal). No mention of prerequisites, such as whether the guide must exist in the collection first.

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

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

With no annotations provided, the description carries the full disclosure burden. It compensates partially by detailing the return payload (content, version hash, rating stats, instructions), which is valuable given the missing output schema. However, it omits operational traits like read-only status, idempotency, or rate limiting that would typically appear in 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 consists of two efficiently structured sentences with zero redundancy. The first sentence front-loads the action and resource, while the second details return values—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 simple 2-parameter schema and lack of output schema, the description adequately compensates by enumerating return fields. It successfully differentiates from sibling tools implicitly through specificity, though it could improve by noting that guides_search typically precedes this call.

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 (both slug and version are documented), the baseline score applies. The description reinforces the primary parameter ('by slug') but does not add significant semantic depth beyond the schema for either parameter, such as example slug formats or version hash syntax.

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 (full content of a guide), and key identifier (slug). It effectively distinguishes from siblings like guides_search (which finds guides) and guides_read_file (which reads specific files rather than full content).

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

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

The description implies usage context by specifying the retrieval method ('by slug') and return contents (stats, instructions), suggesting it's for detailed guide retrieval. However, it lacks explicit guidance on prerequisites (e.g., obtaining the slug via guides_search) or when to prefer guides_read_file for specific files 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?

No annotations are provided, so the description carries full disclosure burden. It fails to describe the return format (list of filenames? metadata objects?), error behavior (what if slug/version invalid?), or whether this is a read-only operation. No mention of pagination or result limits.

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?

Single sentence is appropriately front-loaded and contains no redundancy. However, given the absence of annotations and output schema, the description is arguably too brief to stand alone as sufficient documentation.

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 100% schema coverage, the lack of output schema and annotations creates significant information gaps. The description does not compensate by describing the return structure, leaving agents uncertain about what data structure to expect from the '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 coverage is 100% with clear descriptions ('The guide slug', 'The version hash'), establishing baseline 3. The description mentions 'guide version' which aligns with parameters but adds no additional semantic context about hash formats or slug 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 clearly states the action (List) and resource (files referenced by a guide version). However, it doesn't explicitly differentiate from sibling tool `guides_read_file` (which likely retrieves file contents) or clarify what 'referenced' means in this context.

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

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

No guidance provided on when to use this tool versus alternatives like `guides_get` or `guides_read_file`. No mention of prerequisites (e.g., needing to obtain the version hash beforehand) or when this listing is preferable to other access methods.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It correctly documents that 'version defaults to latest if omitted,' but fails to disclose idempotency (can ratings be updated?), side effects, or authentication requirements for this write 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?

Two efficiently constructed sentences with zero waste: the first establishes purpose and capability, the second provides critical parameter sourcing and default behavior. Information is appropriately 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?

Adequate for a 6-parameter mutation tool with no output schema. Covers the rating action, scale constraints, and version defaulting. Could be improved by clarifying whether subsequent calls update existing ratings or error, given the lack of annotations indicating destructive behavior.

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?

Despite 100% schema description coverage (baseline 3), the description adds valuable sourcing context for the 'slug' parameter ('from search results') and conceptually groups the optional sub-scores, providing semantic value beyond the structured schema.

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

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

The description clearly states the specific action ('Rate'), target resource ('guide version'), and mechanism ('1-5 stars plus optional sub-scores'), effectively distinguishing it from sibling tools like guides_review, guides_get, and guides_search.

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 workflow guidance by specifying to 'Use the slug from search results,' implying a prerequisite search step. However, it lacks explicit differentiation from guides_review or guidance on when not 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?

With no annotations provided, the description carries the full burden. It identifies the operation as a read (non-destructive) but fails to disclose return format (string vs. bytes vs. object), encoding handling, or error behaviors (e.g., file not found scenarios).

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 efficient single sentence with zero redundancy. Every word serves a purpose, front-loading the action ('Read') and qualifying the resource ('content of a file referenced by a guide version').

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 3-parameter tool with complete schema coverage, but lacks necessary context given the absence of an output schema. The description omits what the tool returns (file content as string, JSON, base64?) and how errors manifest, which are essential for a file-reading 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?

Input schema has 100% description coverage, clearly defining slug, version hash, and relative path. The description adds no additional semantics (e.g., that version is likely a git-style hash, or that path must be discovered via guides_list_files), so it meets the baseline 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 clearly states the tool reads file content and references the 'guide version' context from the parameters. It implicitly distinguishes from guides_get (metadata) and guides_list_files (directory listing) by specifying 'content of a file,' though it could explicitly name these siblings for clarity.

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

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

No guidance provided on when to use this tool versus alternatives, nor prerequisites for valid inputs. Missing critical workflow context: users should presumably call guides_list_files first to discover valid path values, but this relationship is not documented.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only mentions the version defaulting behavior. It fails to disclose mutation semantics (create vs. update), persistence details, reversibility, or side effects of submitting a review.

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. The first sentence establishes purpose; the second provides critical usage guidance (parameter sourcing and defaults). 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 this is a write operation with no annotations and no output schema, the description is minimally adequate. It covers the core invocation path but lacks critical behavioral context for a mutation tool (idempotency, error states, output semantics) and fails to differentiate from guides_rate.

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 baseline is 3. The description adds value by specifying that the slug should come from 'search results,' providing sourcing context not present in the schema. It reinforces the version default behavior already documented in the schema.

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

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

The description clearly states the tool 'Write[s] a review for a guide version,' providing a specific verb and resource. However, it does not distinguish this from the sibling tool 'guides_rate,' leaving ambiguity about when to use review vs. rating 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?

The description provides specific guidance on parameter sourcing ('Use the slug from search results') and default behavior ('version defaults to latest if omitted'). However, it lacks explicit when-not-to-use guidance or comparison to sibling alternatives like guides_rate.

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

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

With no annotations provided, the description carries the full burden and successfully discloses the return payload structure (slug, version hash, tags, stats, example calls). However, it lacks safety context (permissions, rate limits) that annotations would typically cover, though 'Search' implies read-only 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?

Two sentences with zero waste: first establishes the search capability, second details the return value. Information is front-loaded and appropriately sized 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?

For a tool with 2 optional parameters and no output schema, the description is complete. It compensates for the missing output schema by explicitly listing return fields and even hints at workflow integration ('example calls for rating and reviewing').

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 mirrors the schema's intent ('keyword and/or tags') but adds no additional semantic detail about parameter syntax, valid tag formats, or query string patterns 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 uses specific verb 'Search' with clear resource 'guides' and filtering mechanisms 'keyword and/or tags'. It effectively distinguishes from siblings like guides_get (direct retrieval), guides_list_files (file enumeration), and guides_rate (action), establishing the discovery-oriented purpose.

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 when to use the tool (when needing to find guides by keywords or tags), but provides no explicit guidance on when NOT to use it, prerequisites, or alternatives such as 'use guides_get if you already have the slug ID'.

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