GitLab Forum 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. It effectively describes the query language syntax and mentions 'Results are permission-aware,' which adds important context about access control. However, it lacks details on error handling, rate limits, or performance characteristics that would enhance 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 is appropriately sized and front-loaded, starting with the core purpose. It efficiently packs detailed query syntax into a single sentence, though the dense listing of options might be slightly overwhelming. Every sentence contributes essential information without waste.

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

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

Given the complexity of the query language and lack of annotations or output schema, the description does a decent job covering input semantics and behavioral context. However, it doesn't explain the return format (e.g., paginated list structure) or error cases, leaving gaps for a tool with rich filtering capabilities.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the 'filter' parameter's query language in detail, but it doesn't provide additional meaning for 'page' or 'per_page' beyond what the schema states. This 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's purpose: 'Filter topics with a concise query language.' It specifies the resource (topics) and verb (filter) precisely, and distinguishes it from siblings like discourse_search (which might be broader) and discourse_list_categories/tags (which list rather than 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?

The description provides clear context for usage by detailing the query language and filterable attributes, implying it's for complex topic filtering. However, it doesn't explicitly state when to use this tool versus alternatives like discourse_search or discourse_read_topic, which could help differentiate further.

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. 'Get basic user info' implies a read-only operation but doesn't specify permissions required, rate limits, error conditions (e.g., invalid username), or what 'basic' entails (e.g., public vs. private data). This leaves significant gaps for an agent to understand the tool's 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 is extremely concise with a single sentence ('Get basic user info.'), which is front-loaded and wastes no words. However, it borders on under-specification, as it could benefit from slightly more detail without losing efficiency.

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 (1 parameter, no nested objects) but lack of annotations and output schema, the description is incomplete. It doesn't explain what 'basic user info' returns, potential errors, or usage context, leaving the agent with insufficient information to use the tool effectively beyond its basic purpose.

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 doesn't mention the 'username' parameter at all, and schema description coverage is 0%, so it adds no meaning beyond the schema. With only one parameter and no schema descriptions, the baseline is 3, as the simple parameter is self-explanatory but undocumented. No compensation is provided 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 'Get basic user info' clearly states the verb ('Get') and resource ('user info'), making the purpose understandable. However, it's vague about what 'basic user info' includes and doesn't differentiate from potential sibling tools like 'discourse_list_user_posts' or 'discourse_list_user_chat_channels' that might also retrieve user-related 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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid username), exclusions, or comparisons to sibling tools like 'discourse_search' that might also find user information. Usage is implied but not explicitly stated.

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

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

With no annotations, the description carries full burden but only states visibility based on auth context. It doesn't disclose behavioral traits like pagination, rate limits, sorting, or what 'visible' entails (e.g., public vs. private categories), which are critical for a list operation.

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

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

The description is a single, efficient sentence with no wasted words. It's front-loaded with the core purpose and includes essential context about auth visibility, making it appropriately sized for a simple 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?

For a zero-parameter list tool with no annotations or output schema, the description is minimally adequate. It covers the basic purpose and auth scope but lacks details on behavior (e.g., output format, limitations), leaving gaps in completeness.

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

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

There are 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description adds value by clarifying the auth context scope, which isn't in the schema, earning a baseline 4 for zero-param tools.

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 ('categories'), specifying they are 'visible to the current auth context'. It distinguishes from siblings like 'discourse_list_tags' or 'discourse_list_drafts' by focusing on categories, but doesn't explicitly differentiate beyond that.

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

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

No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites, exclusions, or compare with other listing tools (e.g., 'discourse_list_tags'), leaving the agent to infer usage based on the name alone.

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

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

No annotations are provided, so the description carries the full burden. It mentions 'if enabled,' which implies a conditional availability, but doesn't disclose other behavioral traits like whether this is a read-only operation, pagination behavior, rate limits, or what happens if tags are disabled. For a tool with zero annotation coverage, this leaves significant gaps.

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

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

The description is extremely concise at just three words, with zero wasted text. It's front-loaded with the core action and resource, and the parenthetical adds necessary context without verbosity. 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 simplicity (0 parameters, no output schema, no annotations), the description is incomplete. It doesn't explain what 'tags' are in this Discourse context, what 'if enabled' entails, or what the return value looks like. For a list operation, even with no parameters, more context on output and behavior would be helpful.

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

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

The tool has 0 parameters, and schema description coverage is 100%, so there's no need for parameter details in the description. The baseline for 0 parameters is 4, as the description doesn't need to compensate for missing schema information. No additional parameter semantics are required.

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

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

The description 'List tags (if enabled)' states the verb ('List') and resource ('tags'), making the basic purpose clear. However, it's vague about what 'tags' are in this context and doesn't differentiate from sibling tools like 'discourse_list_categories' or 'discourse_list_user_posts' beyond the resource name. The parenthetical '(if enabled)' adds some context but doesn't fully specify 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?

The description provides no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (e.g., needing authentication), comparison to similar list tools, or exclusions. The '(if enabled)' hints at a conditional context but doesn't explain what enables tags or when this tool would fail.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Read a specific post,' which implies a read-only operation but does not specify details like authentication requirements, rate limits, error handling, or what data is returned (e.g., content, author, timestamps). This leaves significant gaps for a tool with no 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?

The description is extremely concise with a single sentence ('Read a specific post.'), which is front-loaded and wastes no words. It efficiently conveys the core action without unnecessary elaboration, making it easy to parse.

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 annotations, no output schema), the description is incomplete. It does not explain what 'reading' entails (e.g., output format), potential errors, or usage context. For a tool with no structured support, more detail is needed to guide effective use.

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 one parameter (post_id) with 0% description coverage, so the schema provides no semantic details. The description adds no information about the parameter, such as what post_id represents or how to obtain it. However, with only one parameter and a straightforward tool, the baseline is 3 as the schema minimally defines the requirement.

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 the basic action ('Read') and resource ('a specific post'), which is clear but minimal. It distinguishes from siblings like 'discourse_read_topic' by specifying 'post' rather than 'topic', but lacks detail on what reading entails (e.g., retrieving content, metadata). The purpose is vague beyond the basic verb-noun pairing.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing a valid post_id), exclusions, or comparisons to siblings like 'discourse_read_topic' or 'discourse_list_user_posts'. The description offers no contextual usage information.

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 mentions reading metadata and posts, implying a read-only operation, but doesn't specify authentication requirements, rate limits, error conditions, or what 'first N posts' means in practice (e.g., ordering, pagination). The description is minimal and lacks critical operational context.

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

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

The description is extremely concise—a single sentence that directly states the tool's function without any fluff. It's front-loaded with the core action and resource, making it efficient and easy to parse. 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 3 parameters with low schema coverage (33%), no annotations, and no output schema, the description is insufficient. It doesn't explain return values, error handling, or important behavioral aspects like what 'metadata' includes or how posts are ordered. For a tool with this complexity and lack of structured data, more descriptive context is needed.

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 33% (only start_post_number has a description). The description mentions 'first N posts' which hints at post_limit, but doesn't explain topic_id or provide additional context beyond the schema. Since schema coverage is low (<50%), the description should compensate more but only adds marginal value, warranting a 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 verb 'Read' and the resource 'topic metadata and first N posts', making the purpose unambiguous. It distinguishes from siblings like discourse_read_post (which reads individual posts) and discourse_filter_topics (which filters topics rather than reading a specific one). However, it doesn't explicitly contrast with all siblings, keeping it at 4 rather than 5.

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. It doesn't mention when to choose this over discourse_read_post for reading posts within a topic, or when to use discourse_filter_topics for topic discovery. There's no context about prerequisites, permissions, or typical use cases.

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

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

No annotations are provided, so the description carries the full burden. It only states the action ('search') without disclosing behavioral traits such as authentication requirements, rate limits, whether results are paginated, or what the output format looks like. For a search tool with no annotation coverage, this leaves significant gaps in understanding its 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 is extremely concise with just three words, front-loaded and zero waste. It efficiently conveys the core purpose without unnecessary elaboration, making it easy to scan and understand quickly.

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

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

Given the tool's complexity (search functionality with 3 parameters), no annotations, no output schema, and low schema description coverage, the description is incomplete. It doesn't cover key aspects like result format, error handling, or behavioral constraints, leaving the agent with insufficient information to use the tool effectively.

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 33% (only 'query' has a description), with 3 parameters total. The description adds no meaning beyond the schema—it doesn't explain what 'with_private' does (e.g., include private content) or how 'max_results' affects pagination. It fails to compensate for the low coverage, leaving most parameters undocumented in both schema and description.

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 'Search site content' clearly indicates the verb 'search' and resource 'site content', but it's vague about what 'site content' encompasses (topics, posts, users, etc.) and doesn't distinguish from siblings like discourse_filter_topics or discourse_select_site. It states what the tool does but lacks specificity.

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 on when to use this tool versus alternatives is provided. It doesn't mention when to prefer this over siblings like discourse_filter_topics for filtering or discourse_select_site for site selection, nor does it specify any prerequisites or exclusions. The description offers no usage context.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'validate and select,' which hints at setup and verification, but doesn't explain what validation entails (e.g., checking site accessibility, permissions), whether it stores state for subsequent calls, or any error handling. For a tool with no annotations, this leaves significant gaps in understanding its 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 is a single, efficient sentence: 'Validate and select a Discourse site for subsequent tool calls.' It is front-loaded with the core purpose and wastes no words, making it highly concise and well-structured for quick understanding.

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 (1 parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose and usage context but lacks details on behavioral aspects like validation specifics or state management. Without annotations or output schema, it should do more to compensate, but it meets the minimum for a simple setup tool.

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

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

The input schema has 100% description coverage, with the 'site' parameter documented as 'Base URL of the Discourse site.' The description doesn't add any meaning beyond this, such as format examples or validation rules. With high schema coverage, the baseline score of 3 is appropriate, as the schema handles the parameter documentation 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 clearly states the tool's purpose: 'Validate and select a Discourse site for subsequent tool calls.' It specifies the action (validate and select) and the resource (Discourse site), making it easy to understand. However, it doesn't explicitly differentiate from sibling tools, which are all for interacting with Discourse sites but serve different functions like listing or reading 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 provides clear context on when to use this tool: 'for subsequent tool calls,' implying it should be called first to set up the site for other operations. It doesn't specify when not to use it or name alternatives, but the context is sufficient for basic guidance without being explicit about exclusions.

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