Server Quality Checklist

Tool Scores

• list_pages_in_spaceA
  4/5.0
  Behavior3/5

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

  With no annotations, the description must carry behavioral disclosure. It does disclose the important non-recursive traversal behavior, which is valuable. But it does not describe response shape, ordering, or other runtime behaviors, leaving some burden unfulfilled.

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

  Conciseness5/5

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

  Two compact sentences, with the primary purpose front-loaded and the behavioral caveat placed second. Every clause earns its place; no filler or redundancy.

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

  Completeness4/5

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

  The definition is complete enough for correct invocation: required parameter, optional limit, and the key recursion pattern are covered. However, since there is no output schema, the description does not explain return value structure, which is a minor but real gap.

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

  Parameters3/5

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

  Schema description coverage is 100%: spaceRef and limit are both fully documented with examples and defaults. The description adds only a contextual echo ('nested space's reference'), providing no new semantic information beyond the schema.

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

  Purpose5/5

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

  The description states a specific verb ('List') and resource ('pages directly inside one space'), and explicitly clarifies scope by noting nested spaces are not expanded. This clearly distinguishes it from siblings like list_spaces, list_wikis, and search_pages.

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

  Usage Guidelines4/5

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

  It gives direct usage context for hierarchical descent ('call this again with the nested space's reference to descend'), which is helpful. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of the highest bar.

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

• list_spacesA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the behavioral burden. It usefully discloses that the output includes a reference for list_pages_in_space and that the scope is the configured wiki. It does not mention pagination, ordering, or output shape, but for a simple list operation this is acceptable though not thorough.

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

  Conciseness5/5

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

  Two short sentences communicate the core function, the connection to a sibling tool, and the intended usage context with no filler. 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.

  Completeness4/5

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

  For a single-parameter read-only listing tool, the description plus schema covers what an agent needs: what is listed, the output's purpose, and how to control the result count. A full return-value description is not necessary given the simple nature, though a bit more on output format would make it complete.

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

  Parameters3/5

  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 the sole limit parameter, including its default and bounds. The description adds no parameter-specific details, which matches the baseline of 3 for well-covered schemas.

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

  Purpose5/5

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

  The description names a specific verb and resource: listing the spaces of the configured wiki. It also distinguishes itself by explaining that the result provides the reference needed for list_pages_in_space, which separates it from sibling tools like list_wikis and search_pages.

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

  Usage Guidelines4/5

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

  The instruction 'Use this to orient yourself before browsing' gives clear contextual guidance on when to call it. It does not explicitly describe when not to use it or contrast it with list_wikis, but the purpose is concrete 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.

• list_page_attachmentsA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full behavioral burden. It clearly states that file contents are not downloaded, which is an important behavioral safeguard, and indicates a read-only metadata listing. It does not discuss auth, errors, or rate limits, but for a simple list operation 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.

  Conciseness5/5

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

  Two short sentences contain the essential information, with the main action and output fields front-loaded and the no-download caveat kept as a single clarifying sentence. No filler or redundant wording.

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

  Completeness4/5

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

  For a simple two-parameter tool with no output schema, the description covers the return fields and the key no-download behavior. It omits minor details like ordering or pagination semantics, but the schema already documents the limit parameter, making the description adequately complete.

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

  Parameters3/5

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

  Schema description coverage is 100%, with both pageRef and limit already documented including format, constraints, and default. The description adds no new parameter-level meaning, so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description uses a specific verb-resource pair ('List the files attached to one page') and explicitly names the return fields (name, size, MIME type). This clearly distinguishes it from sibling tools that target pages, spaces, or wikis rather than attachments.

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

  Usage Guidelines4/5

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

  The description gives clear context: it is for listing attachment metadata for one page and not for downloading files. It does not explicitly name alternative tools or provide when-not-to-use guidance, but the one-page scope and no-download caveat make the intended use obvious.

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

• list_wikisA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It does reveal account-scoped visibility and environment dependency (XWIKI_WIKI plus restart), which is useful. However, it does not mention output format, pagination, or explicitly confirm there are no side effects, leaving some behavioral details undisclosed.

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

  Conciseness5/5

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

  The description is two sentences with no wasted words. The core purpose is front-loaded, and the environment-specific guidance is placed after the main definition, making it easy to scan.

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

  Completeness4/5

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

  For a simple zero-parameter list tool, the description covers the key context: account visibility, multi-wiki applicability, and configuration guidance. However, there is no output schema, and the description does not explicitly state the return format (e.g., array of wiki names/IDs), which would round out the context.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema already fully describes the inputs. The description adds value by mentioning the XWIKI_WIKI environment variable as a way to change which wiki is targeted, even though it is not a formal tool parameter. The baseline of 4 for a zero-parameter tool is appropriate.

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

  Purpose5/5

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

  The description states a specific verb ('List'), the resource ('wikis'), and the scope ('this account can see'). It clearly distinguishes this from sibling tools that operate on pages or spaces, so an agent can tell what list_wikis is for without ambiguity.

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

  Usage Guidelines4/5

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

  The description gives clear context by saying it is 'Only relevant on a multi-wiki farm' and explains what to do if the desired wiki is not the configured one. It does not explicitly name alternatives, but sibling tools are sufficiently different that no exclusion is strictly necessary.

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

• search_pagesA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses that the tool is a search operation, lists the returned fields, and signals a read-only, non-destructive action. It omits auth/rate-limit details, but these are not essential for a simple query tool.

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

  Conciseness5/5

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

  Two tight sentences: the first states the operation, scope, and return fields; the second gives the follow-up action. No filler or redundancy.

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

  Completeness5/5

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

  For a two-parameter, no-output-schema tool, the description is complete: it covers what is searched, what is returned, the wiki scope, and how to use the result with get_page.

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

  Parameters3/5

  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 reinforces that query searches names, titles, and content, but adds no parameter details beyond the schema's type, constraints, and defaults.

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

  Purpose5/5

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

  States a specific verb ('full-text search'), a clear resource ('page names, titles and content of the configured wiki'), and the returned hit fields. This distinguishes it from read-single-page (get_page) and listing tools.

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

  Usage Guidelines4/5

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

  The description makes the operation and result shape clear, and explicitly tells the agent to pass the returned pageRef to get_page to read a page. It doesn't explicitly state when to prefer this over list_pages_in_space, but the 'full-text' scope implies the distinction.

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

• get_pageA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It adds meaningful behavioral details: pages are addressed by Space.PageName, bare names fail, and long pages are truncated with an explicit marker. These go beyond a simple 'read a page' statement, though it does not mention error or auth behavior.

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

  Conciseness5/5

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

  Three compact sentences, each earning its place. The main purpose is front-loaded, followed by reference sourcing guidance and a behavioral note about truncation. No redundant or filler content.

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

  Completeness4/5

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

  For a single-parameter read operation with a fully documented schema, the description covers purpose, reference format, reference sourcing, and truncation behavior. It does not describe the exact return format or not-found behavior, but given the low complexity this is a minor gap.

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

  Parameters4/5

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

  The schema already provides 100% coverage for pageRef, so the baseline is 3. The description adds value beyond the schema by giving concrete examples and emphasizing the Space.PageName format and the bare-name restriction, which helps agents construct valid inputs.

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

  Purpose5/5

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

  The description clearly states the action ('Read one page's content by its reference') and distinguishes it from the sibling list/search tools by focusing on content retrieval for a single page. Concrete examples like 'Onboarding.Checklist' and 'Main.WebHome' make the intended use immediately clear.

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

  Usage Guidelines4/5

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

  It explicitly tells the agent to obtain the reference from search_pages or list_pages_in_space, and warns that a bare page name without a space is not addressable. This gives strong usage context, though it does not explicitly list when-not-to-use scenarios or name alternative tools for other cases.

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