Server Quality Checklist

Tool Scores

• get_local_rankingsD
  1.6/5.0
  Behavior1/5

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

  With no annotations, the description carries the full burden of disclosing behavior. It does not mention return format, pagination, auth requirements, rate limits, or any side effects. 'Per-location rank history' is a minimal behavioral hint but far from sufficient.

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

  Conciseness2/5

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

  The description is a single short sentence, but it is under-specified rather than appropriately concise. It lacks essential details and does not effectively front-load useful information beyond a vague mention of local rankings.

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

  Completeness1/5

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

  Given 8 parameters, no output schema, and no annotations, the description is critically incomplete. It fails to explain what the tool returns, how to use its parameters, or any operational behaviors, making it inadequate for reliable invocation.

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

  Parameters1/5

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

  Schema description coverage is 0%, and the description does not compensate by explaining any of the 8 parameters. No light is shed on date formats, granularity options, or the meaning of site_id or search_engine, leaving the agent to infer from parameter names alone.

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

  Purpose3/5

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

  The description 'Local search rankings with per-location rank history' indicates the resource and a distinctive feature, but it lacks a clear verb and does not differentiate from siblings like serp_analytics. It is more a noun phrase than a statement of action, though the 'per-location rank history' adds some specificity.

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

  Usage Guidelines1/5

  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. The description does not mention any context, exclusions, or alternative tools, leaving the agent without information to make a selection decision.

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

• get_llm_filtersC
  2.4/5.0
  Behavior2/5

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

  With no annotations, the description carries full behavioral disclosure burden. It implies a read-only metadata operation but does not mention authorization, error conditions, response format, or how the site_global_key parameter affects results. Minimal behavioral context is provided.

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

  Conciseness3/5

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

  The description is a single sentence with no wasted words, but it is under-specified rather than efficiently complete. It conveys the core purpose but omits necessary context about parameters and usage, making it borderline between concise and inadequate.

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

  Completeness2/5

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

  Given the absence of annotations and output schema, the description is too terse. It does not explain the parameter, the return structure, or the tool's role in relation to other analytics tools, leaving an agent with insufficient information for correct invocation.

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

  Parameters1/5

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

  The schema has 0% description coverage for the sole parameter site_global_key. The description does not mention this parameter or explain its meaning, forcing the agent to infer from the name alone. No added semantic value.

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

  Purpose4/5

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

  The description clearly states the tool returns available filter values for LLM analytics and lists the specific dimensions (channels, LLM names, metrics). This distinguishes it from the sibling llm_analytics tool. However, it lacks an explicit verb, relying on the tool name for the action.

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

  Usage Guidelines2/5

  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 or how it relates to llm_analytics. The description implies a supporting role but does not state prerequisites, sequencing, or exclusion criteria.

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

• get_keyword_citationsC
  2.6/5.0
  Behavior2/5

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

  With no annotations, the description carries full burden. It implies a read-only retrieval ('Citation URLs'), but doesn't disclose any behavioral traits such as authentication, rate limits, data format, or what happens when no citations exist. The description adds minimal value beyond the tool name.

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

  Conciseness4/5

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

  The description is a single, concise sentence that communicates the core purpose without verbosity. However, it omits critical details, so while structured efficiently, it sacrifices completeness.

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

  Completeness2/5

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

  For a tool with four required parameters, no schema descriptions, and no output schema, the description is too brief. It doesn't explain return values, parameter formats, or any edge cases, making it insufficient for an agent to confidently select and invoke it.

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

  Parameters1/5

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

  Schema description coverage is 0%, and the description provides no explanations for any of the four required parameters. It doesn't clarify the meaning of site_global_key, search_engine, target_date, or keyword_name, leaving the agent to infer from property names alone.

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

  Purpose4/5

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

  The description clearly identifies the tool's function: retrieving citation URLs for a single keyword. It distinguishes from sibling tools like get_bulk_citations or get_site_citations by specifying 'single keyword', though it lacks an explicit verb and alternative references.

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

  Usage Guidelines2/5

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

  There is no guidance on when to use this tool versus alternatives. The description simply states the function with no context about conditions, prerequisites, or exclusions. Sibling names imply scope but no explicit instructions.

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

• delete_brandsC
  2.7/5.0
  Behavior2/5

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

  With no annotations, the description carries full responsibility for disclosing behavior. 'Delete' implies a destructive mutation, but it does not mention irreversibility, required permissions, cascading effects, or the behavior of the dry_run parameter. The tool could delete data permanently without any warning.

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

  Conciseness3/5

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

  The description is extremely short and front-loaded, but it is under-specified rather than appropriately concise. It states the core action but omits essential usage details, so the brevity negatively impacts usefulness.

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

  Completeness2/5

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

  For a destructive tool with no annotations and no output schema, the description is not complete enough. It fails to mention the purpose of dry_run, which is a critical safety mechanism, and provides no context about what happens after deletion or how to verify the operation.

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

  Parameters1/5

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

  Schema description coverage is 0%, and the description adds no information about the parameters global_key, brand_ids, or dry_run. It does not explain that dry_run is a preview mode, that brand_ids accepts multiple IDs, or how global_key relates to scoping.

  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 'Delete' with the resource 'brands' and the method 'by ID'. This clearly states what the tool does and differentiates it from sibling tools like list_brands, create_brand, and update_brand.

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

  Usage Guidelines2/5

  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, prerequisites, or safety considerations. Given that this is a destructive operation, it should explicitly mention using dry_run for previewing, but it does not.

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

• get_people_also_askC
  2.7/5.0
  Behavior2/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It only mentions that search intent and AdWords data are optional, but does not describe pagination, date filtering, read-only nature, response format, or any constraints. This is a significant gap for a tool with 9 parameters.

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

  Conciseness4/5

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

  The description is a single concise sentence that front-loads the core purpose. It is efficient and avoids redundancy, but it omits important contextual details, making it too terse for a tool with this complexity.

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

  Completeness2/5

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

  Given the tool has 9 parameters, no output schema, and no annotations, the description is inadequate. It does not explain the required inputs, pagination semantics, or what information is returned. The optional data mentions are helpful but not enough for a production agent to safely invoke the tool.

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

  Parameters2/5

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

  Schema description coverage is 0% for 9 parameters. The description adds meaning for two boolean flags (include_search_intents and include_adword_stats) but remains silent on required parameters (site_global_key, search_engine) and other optional ones (dates, page_limit, keyword_names). It only partially compensates for the schema's lack of descriptions.

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

  Purpose4/5

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

  The description clearly identifies the resource: PAA (People Also Ask) questions from SERPs. While the verb is implicit ('get' is implied by the tool name), the resource is specific and distinct from sibling tools. It does not explicitly differentiate from siblings, but the resource name 'PAA questions' is unique enough to indicate the tool's purpose.

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

  Usage Guidelines2/5

  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 mentions optional inclusions (search intent, AdWords data) but does not explain scenarios, prerequisites, or exclusions. Among many sibling tools, no comparison is offered.

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

• get_landing_matchesC
  2.8/5.0
  Behavior2/5

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

  With no annotations provided, the description alone must disclose behavioral traits. It only mentions the return statuses (match/mismatch/none), but does not state whether the operation is read-only, how errors are handled, how date ranges affect results, pagination behavior, or other important runtime characteristics.

  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 a single sentence with no filler, front-loading the core action and the expected output. It is appropriately concise for the tool's apparent simplicity.

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

  Completeness1/5

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

  The tool has 9 parameters and no output schema, yet the description provides only a high-level purpose. It lacks parameter explanations, return format details, pagination behavior, defaults, and any edge-case handling, making it inadequate for an agent to correctly invoke the tool without further information.

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

  Parameters1/5

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

  Schema description coverage is 0%, and the description provides no explanations for any of the 9 parameters, including required ones like site_id, search_engine, from_date, and to_date. The description does not compensate for the schema's lack of parameter documentation, leaving parameter meaning completely ambiguous.

  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 tool's function: checking whether ranking pages match preferred landing pages, and explicitly lists the three possible statuses (match/mismatch/none). This distinguishes it from sibling tools like get_landings_history, which focuses on historical data rather than match status.

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

  Usage Guidelines2/5

  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, no prerequisites, and no exclusions. It simply states what the tool does, leaving the agent to infer usage from the purpose without explicit instruction.

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

• get_mentionsC
  2.8/5.0
  Behavior2/5

  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 describes the return content but does not disclose whether the operation is read-only, any required permissions, pagination, rate limits, or potential side effects. This is a significant gap for a data-fetch tool without annotation support.

  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 concise and well-structured: the first sentence states the topic, the second lists return types. Both sentences are informative with no redundancy or filler.

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

  Completeness2/5

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

  With 5 parameters, no output schema, and no annotations, the description is insufficient. It lists return categories but does not explain parameter roles, expected input formats, or output structure. It lacks the context needed to invoke the tool correctly beyond basic intent.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description does not compensate. It mentions 'per-keyword' counts, hinting that keyword_tags or keyword_names are relevant, but it does not explain site_global_key, search_engine, target_date, or how keywords are specified. The description adds minimal meaning beyond the schema.

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

  Purpose4/5

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

  The description clearly identifies the tool as returning brand mentions and citations in AI responses, specifying the types of data (counts, context sentences, URLs, client vs competitor breakdown). It distinguishes itself from sibling tools like get_site_citations by focusing on AI responses, though it could be more explicit about being a 'get' operation.

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

  Usage Guidelines2/5

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

  The description provides implied context (for AI response mentions) but gives no explicit when-to-use or alternative comparisons. There is no mention of when to choose this over get_keyword_citations or other sibling tools, leaving the agent to infer usage.

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

• create_brandC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden for behavioral disclosure. It only states the creation action without explaining potential side effects, permissions, idempotency, or response format. This is a significant gap for a mutation 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?

  The description is a single, front-loaded sentence with no extraneous information. It clearly states the tool's purpose and is appropriately concise and easy to parse.

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

  Completeness2/5

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

  The tool is a creation operation with 4 parameters and no output schema. The description provides no information about required fields, parameter meaning, dry-run behavior, or response. Given the lack of annotations and schema descriptions, the description is incomplete for an agent to confidently invoke the tool.

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

  Parameters1/5

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

  The input schema has 4 parameters with 0% schema description coverage. The description mentions none of the parameters (global_key, brand_name, dry_run, brand_description) or their semantics, leaving the agent to infer from parameter names alone. The description adds no value beyond the schema's parameter titles.

  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 'Create' and a resource 'new brand', clearly distinguishing it from sibling tools like update_brand, delete_brands, and list_brands. The phrase 'for GenAI visibility tracking' adds context, making the purpose unambiguous.

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

  Usage Guidelines2/5

  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 like update_brand or delete_brands. There are no prerequisites, exclusions, or context for selecting this over sibling tools. The only implied usage is 'when you need to create a new brand,' which is insufficient.

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

• list_brandsC
  2.9/5.0
  Behavior3/5

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

  No annotations are provided, so the description must disclose behavior. 'List' implies a read-only operation, and the context of 'configured for a site' gives some insight. However, it does not mention authentication needs, pagination, or what exactly constitutes a 'brand' in this context.

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

  Conciseness4/5

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

  The description is a single sentence, front-loaded with the verb and resource. It is concise and to the point, though the parenthetical could be seen as slightly extraneous. It earns its place by adding context.

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

  Completeness2/5

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

  Given the tool has only one parameter, no output schema, and no annotations, the description should offer more context. It doesn't explain the parameter, the return value, or how this tool relates to sibling tools like list_sites or get_mentions. The description is too minimal to fully guide an agent.

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

  Parameters1/5

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

  The schema has one required parameter 'global_key' with 0% description coverage. The description does not explain what 'global_key' refers to (presumably the site identifier) or how to obtain it. With such low coverage, the description should compensate but fails to provide any parameter meaning.

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

  Purpose4/5

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

  The description clearly states the tool lists brands, with the specific context of 'configured for a site' and 'GenAI mention/citation tracking.' This distinguishes it from other brand-related tools like create_brand or delete_brands, though it does not explicitly differentiate it from citation-specific tools like get_mentions.

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

  Usage Guidelines3/5

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

  The phrase 'used for GenAI mention/citation tracking' implies a use case, but there is no explicit guidance on when to choose this tool over alternatives (e.g., get_mentions or get_site_citations). No exclusion criteria or alternative tool mentions are provided.

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

• get_landings_historyB
  3.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description bears the full burden. It discloses the core behavior ('Shows which page ranked on each date'), which is useful context beyond the schema. However, it does not mention return format, pagination, or constraints like date formatting, so the transparency is moderate but not comprehensive.

  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 consists of two concise sentences with no wasted words. It is front-loaded with the tool's purpose ('Landing page history') and immediately follows with the key behavior ('Shows which page ranked on each date'), making it efficient and easy to parse.

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

  Completeness2/5

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

  Given 5 required parameters, no output schema, and no annotations, the description is too sparse to fully enable correct invocation. Users are left to guess date formats, search engine identifiers, and important context about the returned data. The description provides a high-level overview but lacks the detail needed for reliable usage.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate for explaining the parameters. It only vaguely refers to 'a specific keyword' (mapping to keyword_id) and does not explain site_id, search_engine, from_date, or to_date. The bare parameter names are somewhat self-explanatory, but the description adds no additional meaning about formats or allowed values.

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

  Purpose4/5

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

  The description clearly states the tool's function: 'Landing page history for a specific keyword. Shows which page ranked on each date.' This identifies the resource (landing page history) and the specific scope (keyword), which differentiates it from siblings like get_landing_matches that likely focus on current or matching data rather than historical per-date ranks.

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

  Usage Guidelines3/5

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

  The description implies usage for viewing historical ranking data for a keyword, but lacks explicit guidance on when to choose this tool over alternatives such as serp_analytics or get_landing_matches. No exclusions or alternative references are provided, leaving usage to be inferred from the phrase 'for a specific keyword'.

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

• get_site_citationsB
  3.2/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 disclosure burden. It does disclose the paginated nature and the output mapping format, which are useful behavioral insights. However, it omits potential side effects (though likely read-only), rate limits, authentication requirements, or how filtering by keyword_tags might alter the 'all keywords' claim. The description is not rich enough to fully compensate for absent annotations.

  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 exactly two sentences, both informative and front-loaded. It wastes no words, clearly stating the pagination and the keyword-to-URL mapping output. Every sentence contributes to understanding the tool's purpose.

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

  Completeness2/5

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

  With six parameters, no output schema, and no annotations, the description is under-specified. It leaves out required parameter details, the meaning of a 'site_global_key', how pagination interacts with the mapping, and whether keyword_tags narrows the result. The tool's complexity demands a more thorough description to allow correct selection and invocation, especially alongside closely related sibling tools.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate, but it barely does. The term 'Paginated' gives partial meaning to page_limit and page_number, and 'all keywords' suggests keyword_tags is optional filtering. However, it does not explain the necessary parameters site_global_key, search_engine, and target_date, nor does it clarify the behavior of keyword_tags. The description adds minimal value beyond the schema's structural properties.

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

  Purpose4/5

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

  The description clearly states it returns paginated citations for all keywords on a site, producing a keyword→URLs mapping. This conveys the tool's core function and output structure, and the focus on 'all keywords on a site' distinguishes it from sibling tools like get_keyword_citations which likely target individual keywords. However, it does not explicitly differentiate from get_bulk_citations, which might also cover site-wide citations.

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

  Usage Guidelines3/5

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

  The phrase 'for all keywords on a site' implies using this when you need a comprehensive site-level citation view, and the mention of pagination suggests handling large result sets. There is no explicit guidance on when to use this tool instead of alternatives such as get_keyword_citations or get_bulk_citations, nor any exclusions or prerequisites.

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

• get_keyword_groupsB
  3.3/5.0
  Behavior3/5

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

  With no annotations, the description carries the disclosure burden. It does convey the tool's read-oriented nature via 'performance' and lists output components, but it doesn't mention pagination, sorting, date range behavior, or whether it is purely read-only. This adds some context but lacks important behavioral details.

  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 a single sentence, front-loaded with the core purpose and a concise list of output metrics. Every word earns its place; there is no fluff or redundancy.

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

  Completeness2/5

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

  For a tool with 9 parameters, no output schema, and no annotations, the description is too terse. It doesn't explain return structure, pagination behavior, required parameter rationale, or how granularity and sorting affect results. A more complete description is needed for reliable invocation.

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

  Parameters2/5

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

  Schema description coverage is 0%. The description does not mention any of the 9 parameters or their meanings. While parameter names like site_id and from_date are self-explanatory, the description provides no additional guidance on how to use them, especially for less obvious ones like granularity or order.

  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 tool retrieves performance metrics for keyword groups/tags, specifying bucket distribution (bucket0-bucket8), volume, traffic, and CTR. This distinguishes it from sibling tools like get_keyword_citations or get_mentions, which focus on different data types.

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

  Usage Guidelines2/5

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

  There is no guidance on when to use this tool versus alternatives, no exclusions, or context about use cases. The description simply states what it does without any 'when to use' or 'prefer this over' indications.

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

• searchB
  3.3/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral disclosure burden. It usefully states that only record IDs are returned for use with fetch(), but it omits other behavioral details like read-only status, result limits, pagination, or error behavior.

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

  Conciseness5/5

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

  The description is three short sentences, front-loaded with the main purpose, and every sentence contributes meaningful information. There is no redundant or filler content.

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

  Completeness3/5

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

  For a one-parameter search tool with no output schema, the description adequately states the purpose, return type, and covered data categories. However, it lacks important operational details such as query syntax, response limits, pagination, and error conditions, which leaves the description incomplete for an agent to invoke confidently.

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

  Parameters2/5

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

  The schema has only one parameter (query) with 0% description coverage, and the tool description does not explain query syntax, expected format, or how the parameter is used. The listed categories hint at what can be searched, but the description does not compensate for the lack of parameter documentation.

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

  Purpose4/5

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

  The description states the tool searches DemandSphere data and returns record IDs for fetch(), which clearly conveys its core function. It also lists the covered categories, but it remains somewhat generic compared to the many specific get_* sibling tools.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool by listing the data types it covers, but it does not explicitly contrast it with alternatives or state when not to use it. No exclusions or alternative tool references are provided.

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

• update_brandB
  3.3/5.0
  Behavior2/5

  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 'update' without disclosing whether the operation is destructive, how null values affect existing fields, or what dry_run does. The presence of a dry_run parameter is not mentioned, leaving the agent without critical behavioral context.

  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 a single, front-loaded sentence with no superfluous words. It efficiently conveys the core action and target, making it easy to scan.

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

  Completeness2/5

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

  Given this is a mutation tool with 5 parameters, no annotations, and no output schema, the description is far too minimal. It lacks usage context, parameter semantics, behavioral details, and does not explain the dry_run mechanism, making it inadequate for an agent to confidently invoke the tool.

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

  Parameters2/5

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

  Schema description coverage is 0%, yet the description only mentions 'name or description,' hinting at brand_name and brand_description. It does not explain brand_id, global_key, or dry_run, and fails to clarify how null values are interpreted (e.g., do nulls preserve existing values or clear them?).

  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 ('Update'), the resource ('existing brand'), and the specific fields ('name or description'), distinguishing it from sibling tools like create_brand and delete_brands.

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

  Usage Guidelines3/5

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

  The description implies usage (when you need to modify a brand's name or description) but does not explicitly mention when to use this tool versus alternatives, nor does it provide any exclusion criteria or reference to sibling tools.

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

• get_bulk_citationsB
  3.4/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 for behavioral disclosure. It adds useful context by stating the max 50 keyword limit and the return format (keyword→URLs mapping), which goes beyond the raw schema. However, it omits other behavioral aspects like error handling, pagination, data freshness, or authentication requirements, leaving 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.

  Conciseness5/5

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

  The description is highly concise, consisting of two short sentences that are front-loaded with the core purpose. Every word earns its place: it immediately states the tool's output and key constraint (max 50) and describes the return mapping. There is no filler or redundancy.

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

  Completeness2/5

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

  For a tool with 4 required parameters, no schema descriptions, no annotations, and no output schema, the description is too sparse. It provides the basic purpose but leaves the agent without context on how to supply parameters, what values are valid, or what to expect in terms of output structure beyond a vague mapping. The sibling tool list suggests site_global_key might come from list_sites, but the description itself does not mention that dependency.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate for explaining parameters. It only touches on 'keyword_names' implicitly via 'multiple keywords' and the max 50 limit. The other three required parameters (target_date, search_engine, site_global_key) receive no explanation at all, leaving the agent without crucial guidance on formats, allowed values, or how to obtain them.

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

  Purpose4/5

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

  The description clearly states the tool's function: retrieving citation URLs for multiple keywords in a single call. It distinguishes from siblings by explicitly mentioning 'multiple keywords' and the max 50 limit, which sets it apart from single-keyword or site-level citation tools. The verb is implicit, but the noun phrase 'Citation URLs for multiple keywords' is specific enough.

  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 conveys when to use this tool: when you need citations for multiple keywords at once, versus making separate calls. It implies a batch scenario and highlights the 50-keyword cap. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

• llm_analyticsB
  3.4/5.0
  Behavior2/5

  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 disclosing behavioral traits. The term 'analytics' and 'aggregated stats' imply a read-only, non-destructive operation, but the description does not explicitly state this, nor does it mention auth needs, rate limits, or what the response contains. It does not contradict anything, but it leaves significant behavioral aspects undocumented.

  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 compact and well-structured: it opens with the tool's purpose, lists views in a scannable format, and then provides parameter usage notes. Every sentence adds value without redundancy or unnecessary detail, making it easy to parse quickly.

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

  Completeness2/5

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

  Given the tool has 7 parameters, no output schema, and no annotations, the description should cover more ground. It thoroughly explains the view logic and some filters, but omits the purpose of required site_global_key and the date-range parameters, and provides no indication of the return format or data structure. Overall, it is not fully complete for such a complex tool.

  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?

  The description adds meaning to several parameters: it enumerates the possible values of 'view', clarifies that 'metric' is used for non-stats views, and explains that llms_list/channels_list are comma-separated filters applicable to stats/performance views. However, it does not explain to_date, from_date, or site_global_key, which is a notable gap given the schema has 0% description coverage.

  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 tool provides LLM traffic analytics and enumerates multiple views, each with a specific purpose (stats, performance, channels, etc.). This distinguishes it from sibling tools like serp_analytics, which focus on search engine data. The verb+resource is explicit and unambiguous.

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

  Usage Guidelines3/5

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

  The description offers clear context on how to use different views and parameters (e.g., metric for non-stats views, filtering for stats/performance), but it does not discuss when to use this tool versus alternative analytics tools, nor does it mention any exclusions. Usage guidance is implied rather than explicitly framed as a choice among siblings.

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

• serp_analyticsB
  3.4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It does reveal the output nature of each view (e.g., 'per-keyword rank, traffic, CTR' and 'rank history over time'), which is meaningful. Yet it omits other behavioral aspects like pagination, sorting defaults, data freshness, or error conditions, leaving gaps in expected behavior.

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

  Conciseness4/5

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

  The description is compact and packs a lot of information into a single sentence using a colon-separated structure. Each view clause earns its place, though it could have been made more scannable with bullet points or line breaks. No fluff is present.

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

  Completeness2/5

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

  The tool is complex with 12 parameters, no output schema, and no annotations. The description explains the four view modes and their dependencies but does not cover return-value structure, pagination behavior, grouping, sorting options, or how search_engine and dates interact. This is insufficient for an agent to confidently invoke the tool without guessing.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate. It explains the semantic meaning of 'view' values and clarifies that global_key vs site_id is required per view. However, it does not address the other nine parameters (limit, order, grouped, sort_by, page_num, granularity, etc.), leaving most of the schema unexplained.

  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 defines the tool as SERP analytics with multiple views and enumerates each view's specific output (rank, traffic, CTR, rank history, engine comparison, aggregate metrics). This distinguishes it from the more specialized sibling tools like get_local_rankings or get_mentions by framing it as a multi-view analytics resource.

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

  Usage Guidelines3/5

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

  The description gives concrete usage context by stating which identifier each view requires (global_key vs site_id), which helps the agent choose the right view. However, it does not mention when to prefer this tool over sibling analytics tools, nor does it state any exclusions or alternative tool comparisons.

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

• fetchA
  3.5/5.0
  Behavior2/5

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

  No annotations are provided, so the description alone must disclose behavior. It only states the action and source of the ID; it does not mention error handling, return format, or permission requirements, leaving gaps for a read operation.

  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?

  A single sentence with no filler, front-loaded with the verb and object, and directly useful.

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

  Completeness3/5

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

  For a simple one-parameter retrieval tool, the description covers what and when to use it. However, without annotations, error cases and response shape are left implied, making it minimally complete but not richly informative.

  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?

  The schema defines only record_id with no description. The description's 'by ID' confirms the parameter's role and ties it to previous search results, but it adds no further detail about format or required context. For a single-parameter tool this is adequate but minimal.

  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?

  Clearly states it fetches a record by ID, and specifies the record must come from a previous search() call. This distinguishes it from sibling tools like search and list_sites.

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

  Usage Guidelines3/5

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

  Implied usage is after a search() call, as the ID comes from search results. No explicit when-not-to-use or alternative tools are mentioned, but the primary context is clear.

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

• list_sites_flatA
  3.8/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It clearly states that the tool returns a flat array with id, name, url, and keyword count, but it does not mention ordering, pagination, or any limitations. For a simple read-only list, this is acceptable but not rich.

  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 a single, concise sentence that states the purpose and return fields. It is front-loaded and contains no filler or redundant information.

  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 zero-parameter, flat-list tool, the description is nearly complete. It lists the return fields but does not specify data types or ordering. Given the lack of an output schema, a bit more detail (e.g., data types or examples) would push it to a 5, but the current level is sufficient for basic use.

  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 provides complete coverage. Per the baseline, 0 parameters earns a 4. The description adds no parameter-related detail because there are none, but no compensation is needed.

  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 ('List') and resource ('sites') and specifies the return format ('flat array'), which distinguishes it from sibling tools like list_sites that may return a hierarchical structure. It also lists the returned fields, leaving no ambiguity about what the tool does.

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

  Usage Guidelines2/5

  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 such as list_sites. It does not state any contexts or exclusions, leaving the agent to infer when this flat list is preferable to other site-related tools.

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

• list_sitesA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description must disclose behavioral traits. It states the output includes site IDs and that it lists all sites, implying a read-only operation. However, it does not describe the exact response structure, pagination, or any potential side effects. For a simple list tool this is adequate but not comprehensive.

  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 a single, front-loaded sentence that clearly states the action, scope, and return value. Every word adds value with no redundancy or filler.

  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 straightforward zero-parameter tool, the description is mostly complete. It explains the purpose and what is returned. However, it lacks explicit mention of whether the hierarchy is nested or flat, and there is no output schema to clarify the response format. Still, it is sufficient for an agent to decide to invoke it.

  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 no parameters (0 params), so the baseline is 4. The description adds context about the output (site IDs) but no parameter-specific details are needed. The schema coverage is trivially 100%.

  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 action ('List all sites') with a clear scope ('with org/account hierarchy') and differentiates from the sibling tool 'list_sites_flat' by implying hierarchy vs flat view. It also mentions the return value ('site IDs needed by other tools'), which clarifies its purpose.

  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 implicitly indicates when to use the tool: when you need site IDs for other tools. It does not explicitly name alternatives or exclusions, but the contrast with 'list_sites_flat' is evident from the sibling list. The guidance is clear enough for a simple listing operation.

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