Server Quality Checklist

Tool Scores

• harness_searchA
  3.6/5.0
  Behavior3/5

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

  Annotations already establish read-only and non-destructive behavior, so the bar for additional disclosure is moderate. The description adds useful context by saying results are ranked by relevance and that scope can be supplied via a Harness URL. It does not address pagination or response shape, but the output schema reduces the need for those 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, front-loaded sentence with no filler. It states the core operation first, then adds the two most useful behavioral cues: relevance ranking and URL-based scoping.

  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?

  Given the rich input schema, safety annotations, and presence of an output schema, the description covers the essential selection cues: multi-type search, relevance ranking, and scope handling. It does not explicitly explain when to prefer this over sibling tools, but the residual burden is mostly carried by the structured metadata.

  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%, and the schema itself is rich, including explicit warnings about org_id and project_id having no configured default. The description's only parameter-related phrase ('Accepts a Harness URL for scope') largely duplicates the existing url parameter description, so it adds little beyond the baseline.

  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 a specific verb and resource ('Search across multiple Harness resource types'), notes that results are relevance-ranked, and mentions URL-based scoping. This is clear enough to distinguish it from sibling tools like harness_list, harness_get, and harness_describe, though it does not explicitly name those alternatives.

  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 'multiple resource types' and 'ranked by relevance' framing implies this is the tool for broad cross-resource search, but it does not explicitly say when not to use it or point to alternatives such as harness_list or harness_get for known IDs or single types. The usage guidance is therefore present only by implication.

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

• harness_updateA
  3.7/5.0
  Behavior3/5

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

  Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds useful context about passing a Harness URL for identifier extraction and the openInHarness response link. It does not disclose overwrite consequences, confirmation expectations, or failure behavior, so the destructive nature is only partially explained beyond the 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 three sentences with no filler. It front-loads the core purpose, then gives the most important usage variation, a shortcut, and the response link. Every sentence earns its place.

  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?

  Given the 9-parameter schema, output schema, and safety annotations, the tool is well-covered. The description provides the key behavioral notes, while the schema handles default-scope, confirm, and identifier details. It could be even more complete with explicit create/delete routing, but that gap is minor.

  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?

  Schema description coverage is 100%, so the baseline is 3. The description adds practical value by recommending a YAML string for complex pipeline/input-set definitions and noting URL-based auto-extraction of identifiers, which goes beyond the schema's per-parameter text. It does not need to enumerate every parameter.

  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 a clear verb and resource: 'Update an existing Harness resource.' It also gives concrete body-format guidance for pipelines/input sets, which helps disambiguate this from harness_create or harness_delete. It does not explicitly name those sibling tools, so it falls short of full differentiation.

  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 word 'existing' implies this is for modifying resources that already exist, and the pipeline/input-set body guidance provides useful procedural direction. However, the description does not explicitly say when to prefer this over harness_create or harness_delete, nor does it name alternatives or exclusions.

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

• harness_diagnoseA
  3.8/5.0
  Behavior4/5

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

  Annotations already carry the safety profile (readOnlyHint=true, destructiveHint=false), so the description only needs to add behavioral context — which it does by disclosing URL-based auto-detection of resource type and the pipeline-execution default. The schema's options text further discloses consequential behavior: pipeline diagnosis requires a completed execution, all-step logs are fetched in batches of 3 with a memory cap, and ?step= URLs trigger targeted single-step log retrieval. No contradiction with annotations; openWorldHint aligns with the connectivity-testing 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 sentences with zero filler and the most decision-relevant fact (what the tool does) front-loaded first. The purpose list, the default behavior, and the URL-acceptance capability each earn their place and are ordered from broad purpose to specific behavior to input mechanism.

  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 complex tool with six parameters and a nested options object, the combination of description, rich schema, and annotations gives an agent everything needed to invoke it correctly. An output schema exists, so return-value documentation is not required. The main description doesn't enumerate supported resource types, but the resource_type enum covers that, and the only real gap is the absence of sibling-routing guidance.

  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%, and each parameter description is unusually rich: url explains auto-extraction, org_id/project_id warn there is no configured default and instruct the agent to pass them on the first call, and options documents nested behaviors like log batching and memory caps. The main description only repeats the url auto-detection concept already present in the resource_type and resource_id parameter descriptions, adding no new semantic value. The baseline 3 applies because the schema does the heavy lifting.

  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 a specific verb (Diagnose) and a clear resource scope, enumerating four concrete purposes (analyze failures, test connectivity, check health, troubleshoot GitOps sync). The default-to-pipeline statement adds further specificity and helps distinguish it from search/get/describe siblings. It loses a point because 'a Harness resource' is generic and it never explicitly contrasts itself with harness_status, which could plausibly overlap with 'check health.'

  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 the diagnostic use case through its purpose list and states the default path (pipeline execution diagnosis), giving an agent a sense of when to call it. However, it offers no explicit when-not-to-use guidance and no comparison against harness_status or harness_search, which an agent might reasonably confuse with this tool. The single pointer to harness_describe lives inside the schema's options description rather than the main description.

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

• harness_listA
  3.8/5.0
  Behavior4/5

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

  Annotations already indicate read-only and non-destructive behavior. The description adds meaningful behavioral context beyond those hints: a URL can auto-extract scope, and project-scoped calls require org_id/project_id on the first call because this session has no configured default. This is useful interaction nuance that the annotations alone do not convey.

  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 sentences, starts with the core operation, and then gives the most important scope caveat. Every sentence earns its place and there is no fluff.

  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?

  Given the tool's complexity—11 parameters, nested objects, a large resource_type enum, and an output schema—the description supplies the essential operational context: listing, filtering, pagination, URL-based scope extraction, and first-call scoping requirements. It does not restate per-parameter details, which is acceptable because the schema and harness_describe references cover them.

  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 parameters thoroughly. The top-level description mostly restates what the url, org_id, and project_id field descriptions already say, without adding new syntax or interaction details beyond those fields.

  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 uses a specific verb ('List') and names the resource class (Harness resources) plus filtering and pagination, so an agent can tell this is a collection operation. It does not explicitly differentiate it from harness_search or harness_get, which are present as siblings, so it falls short of the top bar for sibling distinction.

  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 provides practical scope-handling guidance: a Harness URL auto-extracts scope, and project-scoped types need org_id and project_id on the first call unless a default is configured. However, it does not state when to prefer this tool over harness_search, harness_describe, or harness_get, nor does it offer exclusions or alternative routing.

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

• harness_createA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the write nature is established without the description needing to restate it. The description adds useful behavioral context around input formats (YAML vs. JSON) and remote-pipeline parameter requirements, but does not disclose other behavioral traits like confirmation/risk or failure modes. This is adequate 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 dense, information-rich, and front-loads the core action before branching into scenario-specific details. Every sentence covers a distinct case: basic create, YAML vs. JSON body formats, remote Git params, and a fallback for other resource types. There is no filler or repetition.

  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 create tool with 8 parameters and a large resource_type enum, the description covers the most complex cases (pipelines, input sets, remote Git vs. Harness Code) and provides a sensible catch-all for other resource types via harness_describe. The output schema exists, so return values need not be described. It does not explain scope/org/project requirements, but those are fully covered in the schema, and the openWorldHint annotation further supports discoverability.

  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 fully documents all parameters. The description does add a recommendation ('recommended for complex definitions') and scenario-to-parameter mappings for remote Git and Harness Code, but these largely echo what the params and body descriptions already state. It adds marginal value beyond the schema, not substantial new semantics.

  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 opens with a specific verb and resource ('Create a Harness resource'), immediately establishing the operation. It goes on to distinguish key sub-flows (pipelines/input sets vs. remote pipelines vs. other resources), and the sibling list confirms the separation from harness_get/update/delete/list/describe. Nothing about the purpose is vague or tautological.

  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 concrete usage guidance for the main branches: YAML strings for pipelines/input sets, git details for remote pipelines, and explicitly routes users to harness_describe for body formats of other resources. It lacks explicit 'when not to use this tool' guidance versus harness_update, but the create semantics and scenario-specific instructions provide clear context.

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

• harness_deleteA
  4/5.0
  Behavior4/5

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

  Annotations already mark destructiveHint=true, and the description reinforces this with 'destructive and cannot be undone,' adding irreversibility context. It also discloses the URL auto-extraction behavior, though it does not mention confirmation requirements or side effects beyond deletion.

  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, front-loaded with the core action. The irreversibility warning is the most important non-schema context and is placed at the end without padding.

  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?

  Complexity is high (8 params, nested objects, enums), but the schema is unusually rich and annotations cover the read/write/destructive profile. The description does not need to explain return values because an output schema exists. The only minor gap is that the confirm workflow is not surfaced in the description, though the schema documents it thoroughly.

  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 baseline is 3. The description's URL auto-extraction point is already captured in the url parameter's schema description. It does not add new parameter semantics beyond what the schema already provides.

  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 opens with a specific verb and object, 'Delete a Harness resource,' clearly identifying this as the deletion tool among siblings like harness_create and harness_update. It also adds a distinguishing capability (URL auto-extraction), so an agent can select it without opening the schema.

  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 deletion usage but does not explicitly state when it should be chosen over sibling tools or when it should not be used. No alternatives are named, though the destructive warning provides some cautionary context.

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

• harness_describeA
  4.3/5.0
  Behavior4/5

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

  Annotations already mark the tool as read-only and non-destructive, and the description adds meaningful context beyond annotations: 'No API call — returns local metadata only.' This clarifies that the tool performs no network operation and has no side effects, which is valuable for an agent deciding how to invoke it.

  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 with no wasted words. It front-loads the core purpose, then adds the critical behavioral qualifier ('No API call'), and closes with usage guidance. Every sentence earns its place.

  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?

  Given the output schema and annotations, the description is complete for an agent to select and invoke the tool. It explains why the tool exists, what it returns at a high level, and that it is purely local. No additional behavioral or usage detail is necessary for correct invocation.

  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 all three parameters: toolset, search_term, and resource_type. The description adds no parameter-level detail beyond the schema, but it aligns the tool's discovery purpose with the resource_type parameter. Baseline 3 is appropriate because the schema carries the semantic load.

  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 a specific verb and resource: 'Describe available Harness resource types, their supported operations, and fields.' It further distinguishes itself from sibling tools by noting 'No API call — returns local metadata only,' making its discovery-focused role distinct from execution and retrieval 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 explicitly says when to use it: 'Use this to discover what resource_types you can use with other harness_ tools.' It provides clear context but does not name specific alternative siblings or state when not to use them, so it falls short of full exclusionary guidance.

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

• harness_getA
  4.3/5.0
  Behavior4/5

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

  Annotations already cover read-only and non-destructive behavior, so the description's extra value is the URL auto-extraction behavior, which is a meaningful operational trait not visible in the schema. It does not contradict the annotations and doesn't need to restate safety.

  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 sentences with no filler: the core operation, the URL capability, and a routing caveat. Every sentence earns its place and the most important info is front-loaded.

  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?

  Between the schema's per-parameter guidance, the output schema, and the annotations, the agent has what it needs to call and interpret results; the description adds the URL parsing and diagnose routing that structured fields don't convey. For a broad resource-type tool, this is complete enough.

  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?

  Input schema covers all 8 parameters with detailed descriptions (100% coverage), including required-context warnings for org_id/project_id and resource_type/resource_scope enums. The description adds only an overview-level URL auto-extraction hint, which is appropriate given the schema's richness.

  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?

  Description opens with a clear verb+object structure — 'Get a Harness resource by ID' — and adds the URL auto-extraction mechanism, so an agent knows exactly what this tool retrieves. Naming harness_diagnose as the failure-analysis alternative distinguishes it from an important sibling. It is specific 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 Guidelines4/5

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

  The final sentence gives an explicit routing rule: for failure analysis, prefer harness_diagnose. The URL auto-extraction note also signals that the tool is appropriate when a Harness URL is available. It does not spell out when to choose harness_search/list over this tool, but the by-ID scope implies those cases.

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

• harness_statusA
  4.3/5.0
  Behavior4/5

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

  With readOnlyHint and destructiveHint already indicating a safe read operation, the description adds useful detail about the live nature of the data and the specific categories covered. It also explains the URL auto-extraction behavior, which goes beyond the schema and 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?

  Two sentences, no filler. The headline purpose comes first, followed by the key input shortcut and a concrete usage example. Every sentence earns its place.

  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?

  The attributes fully describe the tool's purpose, usage context, key behavioral trait (URL auto-extraction), and input semantics. With an output schema present and safety annotations covering side effects, nothing essential is missing for an agent to invoke this correctly.

  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 fully documents all four parameters. The description adds the useful context that a URL can auto-extract org and project, but it does not need to repeat parameter details. A 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 combination ('Get a live project health overview') and enumerates exactly what it returns: failed executions, running executions, and deployment activity. This clearly distinguishes it from generic search/list/get siblings like harness_list and harness_get.

  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 explicit context for when to use it: 'Ideal first question: what's happening in my project right now?' This is clear and actionable, though it does not spell out exclusions or alternatives beyond implicitly being the first-stop overview tool.

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

• harness_executeA
  4.4/5.0
  Behavior4/5

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

  Annotations already mark destructive/readOnly/idempotent behavior, and the description adds useful behavioral context beyond them: server-side blocking wait to terminal status, URL auto-extraction of identifiers, and that wait is ignored for non-pipeline actions. It could say more about side effects of disruptive actions like kill or interrupt, but the destructiveHint covers the safety signal.

  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 dense sentences front-load the tool's action role, then cover the two most non-obvious usage patterns: URL auto-extraction and blocking wait, plus HQL batch. No filler or repetition of the schema.

  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 16-parameter, open-world action tool, the description plus the highly detailed schema and output schema provide sufficient initial orientation. It does not enumerate every resource_type/action combination, but it points to harness_describe for params and runtime_input_template via harness_get, and uses examples to establish the pattern.

  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?

  Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter recipes—queries plus resource_type='hql_query' plus action='validate'/'run', and wait plus pipeline run/retry—that are not inferable from individual parameter docs. Since the schema is already very detailed, this is strong but not maximal.

  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 ('Execute an action') and resource ('Harness resource'), then enumerates representative operations that differentiate it from read/list/delete tools: run/retry/interrupt pipelines, kill/restore FME flags, test connectors, sync GitOps, run chaos experiments. This makes its role as the side-effecting action tool unmistakable.

  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 concrete usage recipes: use wait:true for pipeline run/retry to avoid a polling loop, and use queries with resource_type='hql_query' for HQL batch operations. It does not explicitly contrast with sibling tools like harness_update or harness_delete, so it misses the explicit when-not/alternative criterion for a 5.

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

• harness_schemaA
  4.7/5.0
  Behavior5/5

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

  Annotations already mark the tool as read-only and non-destructive, and the description adds meaningful behavioral detail beyond that: bundled vs live-fetched schema sources, the requirement for scope/org_id/project_id on live entities, and the automatic placeholder identifier behavior. The precedence behavior is also disclosed. This gives an agent an accurate model of how the tool behaves.

  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 dense but well organized, moving from the core purpose to usage modes to precedence to the available schema list. Almost every sentence earns its place. The final 'Available schemas' list duplicates the resource_type enum, which is minor redundancy, but the description remains efficient and scannable.

  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 tool with 8 parameters, multiple source backends, and several operation modes, the description is remarkably complete. It covers all parameter combinations, precedence, scope constraints, and the distinction between bundled and live schemas. The presence of an output schema reduces the need to describe return values, and nothing critical is left ambiguous.

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

  Parameters5/5

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

  Although the schema already documents all parameters at 100% coverage, the description adds substantial semantic value beyond the schema. It explains how path, example, and example_search interact, when scope/org_id/project_id are required, and how identifier behaves for create-time vs update-time lookups. This transforms a list of parameters into an actionable decision procedure.

  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 opens with a specific verb and resource: 'Fetch Harness YAML schema or examples for a resource type.' It clearly distinguishes this tool from the create/update/delete/get/search siblings by focusing solely on schema and example retrieval. The supported resource types and operation modes are enumerated.

  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 concrete usage guidance: use without path for a summary, use with path to drill in, use with example for named snippets, and use with example_search for keyword exploration. It also states the precedence order example > example_search > path > summary. However, it does not explicitly say when NOT to use this tool versus alternatives like harness_get or harness_describe, so it stops 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.