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

The description gives no behavioral details beyond the basic action. It does not disclose whether content is returned to the LLM, how save_path affects behavior, or if there are side effects, which is notable given openWorldHint is true and readOnlyHint is false.

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

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

The description is a single sentence but it largely restates the tool name and title. It is under-specified rather than appropriately concise, offering little value beyond the structured metadata.

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 having an output schema and good parameter descriptions, the tool description lacks prerequisite context, usage scenarios, and behavioral expectations. For a download tool, this minimal description is insufficient for an agent to know when and how to 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?

Schema coverage is 100%, with both parameters well-described: save_path explains save vs. return behavior, and attachment_id provides a concrete example. The description itself adds no parameter semantics, but the schema compensates fully.

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 'Download attachment content' uses a specific verb and resource, clearly indicating the tool's function. It distinguishes itself from siblings like get_content_by_id, which retrieves content rather than downloading attachments, though it omits the Confluence context explicitly.

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 about when to use this tool versus alternatives such as get_content_by_id or get_comments. The description is a bare statement with no context on prerequisites, exclusions, or appropriate 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?

Annotations already declare read-only and non-destructive behavior. The description adds valuable technical detail about footer vs. inline comments and the markerRef UUID, which is not visible in annotations or schema alone. No contradiction found.

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 concise sentences with front-loaded purpose and zero fluff. The structure efficiently conveys purpose, return content, and special input handling.

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 rich schema and output schema, the description adds the key non-obvious behaviors (inline markerRef and reply thread handling) without redundant details. It fully equips an agent to use the 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%, so the description adds no additional parameter meaning. The schema already explains id, depth, limit, start, and save_path. The tool description simply restates the id behavior already present 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 retrieves comments by content ID, distinguishing between page comments and comment threads. The verb 'Get' and specific resource make it distinct from siblings like get_content_by_id or 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 concrete usage context: passing a page ID returns comments, passing a comment ID returns its reply thread. It does not explicitly name alternative tools, but the behavior is clear enough for an agent to select this tool when comments are needed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral detail by specifying that the body is in storage format HTML and listing returned items (ancestors, child pages, attachments), going beyond what annotations provide.

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

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

The description is two short sentences. The first sentence states the core action and the second lists return content. No filler words or redundant information.

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

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

For a simple read-only tool with annotations and an output schema, the description is fairly complete. It lists the main return fields. However, it does not mention error behavior, how status affects the result, or alternative tools, but these are not critical given the simplicity.

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

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

Schema description coverage is 67% (id and save_path are described, status is not). The description only reinforces that 'id' is a content ID, adding no additional meaning. It does not mention the status or save_path parameters, leaving the uncovered status parameter unexplained.

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 'Get content by ID' and lists the returned fields, making it a specific verb+resource. However, it does not explicitly distinguish itself from sibling tools like search or get_comments, so it lacks explicit sibling differentiation.

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 usage context is implied: use this tool when you have a content ID. However, there is no explicit guidance on when to use this tool instead of alternatives like search or get_spaces, nor any mention of when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the tool returns key and name and supports filters, but it doesn't disclose extra behavioral traits like pagination behavior or response structure beyond what the schema/annotations imply.

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 and front-loaded: 'Get spaces. Returns key and name. Filter by space_key, status, label, favourite.' Every sentence adds value 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?

For a 7-parameter tool, the description covers purpose, return fields, and key filters, but omits guidance on pagination parameters (limit, start) and doesn't clarify valid status values. The output schema exists, so return values are presumably structured, but the description alone is not fully complete.

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

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

Schema description coverage is only 14% (only save_path has a schema description). The tool description names four filters (space_key, status, label, favourite) but doesn't explain their value formats or semantics (e.g., valid status values, boolean usage for favourite). It adds little over the schema's type definitions.

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

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

The description clearly states the action ('Get spaces') and the resource (Confluence spaces), and notes the return fields (key and name). However, it does not explicitly distinguish this from sibling tools like search or get_content_by_id, though the resource is distinct.

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 by listing available filters (space_key, status, label, favourite), giving context for when to call it. It lacks explicit guidance on when not to use it or when to prefer alternatives such as search, so it falls short of a 4.

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, which the description does not contradict. The description adds value by specifying the return fields (displayName, username, userKey) and the two lookup methods, providing more behavior context than annotations alone.

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

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

The description is two sentences, front-loads the core action, and conveys both input criteria and output fields without any wasted words 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?

Given the simple nature of this read-only tool, the presence of an output schema and safety annotations, the description sufficiently covers purpose and inputs. A minor gap is that it does not specify behavior when both or neither parameter is provided, but this is not critical for a straightforward user profile fetch.

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% coverage with detailed descriptions and examples for both parameters (key and username), including source hints like 'ri:userkey in page body HTML'. The description adds no additional semantic detail beyond what the schema already provides, so baseline 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 'Get user profile' with specific identifiers (username or userKey) and lists the return fields. This unambiguously distinguishes it from sibling tools like get_content_by_id or search, which target different resources.

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 clear context for when to use the tool ('Get user profile by username or userKey') and explains the two input options. It does not explicitly name alternatives or exclusions, but sibling tools are clearly unrelated, making the usage context sufficient.

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

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

Beyond the annotations (readOnlyHint, destructiveHint), the description adds meaningful behavioral details: filters are combined with AND, and pagination is handled via start/limit with a hasMore indicator in the response. This enriches the agent's understanding of the tool's behavior without repeating annotation info.

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, front-loaded with the core purpose ('Search Confluence'), then immediately provides essential usage details. Every sentence earns its place with no wasted words.

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

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

Given the 14 parameters and existing output schema, the description covers the key cross-cutting behaviors (filter combination, pagination) adequately. It does not mention the save_path parameter, but that is documented in the schema, and the output schema reduces the need to describe return values.

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

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

With 86% schema description coverage, the schema already documents most parameters. The description adds global semantics: 'All filters are combined with AND' explains how multiple query params interact, and the pagination note clarifies start/limit usage, going beyond the individual parameter descriptions.

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

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

The description states 'Search Confluence' with a specific verb and resource, clearly distinguishing this tool from sibling tools like get_content_by_id or get_spaces, which are direct lookups rather than general search. The purpose is unambiguous.

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

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

The description gives 'All filters are combined with AND' and pagination guidance, providing clear context on how to use the tool's parameters. However, it does not explicitly state when to prefer this tool over siblings or provide exclusions, leaving some implied usage based on the name 'search'.

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