Server Quality Checklist

Tool Scores

• bourne_execution_reconcileA
  3.5/5.0
  Behavior3/5

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

  Annotations already communicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds useful behavioral constraints like targeting exactly one execution and never resubmitting, but it does not explain what 'reconcile' actually does, what side effects may occur, or whether permissions or prerequisites are needed.

  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. Every word contributes: the action, the scope, the ownership constraint, and the critical 'never resubmit' warning.

  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?

  Although the tool has only one parameter and an output schema, the description leaves the meaning of 'reconcile' vague and gives no trigger conditions or behavioral detail beyond 'never resubmit.' An agent can avoid resubmission but cannot reliably know when or how to invoke this 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%, and the description never mentions the 'reference' parameter. The name implies it is an identifier, but the description does not connect it to the execution being reconciled or explain what form it should take.

  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 ('Reconnect and reconcile') and a precise resource ('one exact Bourne-owned remote execution'), then adds a clear negative constraint ('never resubmit'). This distinguishes it from resubmission-style siblings and makes the tool's scope obvious.

  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 usage context is implied: use this when reconnecting a Bourne-owned execution to reconcile its state. However, there is no explicit when-to-use guidance, no mention of when not to use it, and no naming of alternative tools such as bourne_execution_get or bourne_execution_wait.

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

• bourne_trace_artifactA
  3.5/5.0
  Behavior3/5

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

  Annotations already establish the read-only, idempotent, and non-destructive nature of the tool. The description adds a useful behavioral trait — 'without guessing across ambiguous matches' — but it does not explain what happens on ambiguity (returned matches, an error, or a disambiguation prompt). This keeps it slightly above the baseline but not fully transparent.

  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, front-loaded sentence states the primary action, the target resource, and the expected output, ending with a caveat that carries meaningful behavioral value. There is no filler, repetition, or unnecessary detail.

  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 one-parameter, read-only tool with annotations and an output schema already provided, the description covers the essential scope and behavioral guarantee. The main gap is path-format documentation, but the risk is moderate given the low complexity and the supporting structured metadata.

  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 one parameter, 'path', with 0% description coverage, so the description must compensate. It only says the tool traces 'a recorded output artifact' and does not clarify whether path is a filesystem path, an artifact ID, a URI, or where the path comes from. This is insufficient for reliable invocation.

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

  Purpose5/5

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

  The description names a specific verb ('trace') applied to a specific resource ('a recorded output artifact') and specifies the expected results: producer, inputs, and experiment ancestry. This clearly differentiates it from sibling tools like execution_get and inventory, which address different concerns.

  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 given about when to prefer this tool over alternatives, nor are any exclusions or prerequisites mentioned. The description tells the agent what the tool does but not how to decide between this and related discovery/tracing tools, leaving the selection to inference.

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

• bourne_execution_getA
  3.6/5.0
  Behavior4/5

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

  Annotations already establish read-only and idempotent behavior. The description adds meaningful context by listing the exact state categories returned (telemetry, verification, etc.), telling the agent what data to expect. It does not contradict 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?

  A single, front-loaded sentence that efficiently communicates the core purpose and the scope of the returned data. No extraneous words or fluff.

  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?

  The output schema covers return values, so that is not needed. However, the missing reference-format details and lack of guidance on when to use this over sibling read-ish tools leave minor gaps. Given the simplicity of a one-parameter read-only tool, this is adequate but not fully comprehensive.

  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 no description for 'reference' and the tool description does not clarify its format or how to obtain it. With 0% schema coverage, the description should compensate but does not; it only implies an execution identifier through the tool name.

  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 clearly states the action ('Read') and the resource ('a Bourne execution'), and enumerates the specific state components included (request, plan, lifecycle, etc.), distinguishing it from sibling tools like cancel or wait. It is unambiguous 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 does not indicate when to use this tool versus alternatives such as bourne_execution_reconcile, wait, or cancel. It only describes the function, leaving the agent to infer that this is the standard read operation. No exclusions or alternatives are mentioned.

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

• bourne_site_inspectA
  3.6/5.0
  Behavior3/5

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

  Annotations clearly mark the operation as read-only and idempotent, so the description does not need to disclose safety traits. The description adds useful context about the inspected entities (policy claims, inventory identities) but does not reveal behaviors such as error handling, result shape specifics, or any authoritative constraints that go 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?

  A single, tight sentence that captures the essential purpose. It is front-loaded, easy to parse, and contains no extraneous details.

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

  Completeness4/5

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

  The description adequately summarizes the tool's behavior given the single parameter and read-only annotations. An output schema exists, so omitting return details is acceptable; the only notable absence is explicit routing guidance among the many sibling site tools.

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

  Parameters3/5

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

  Schema coverage is 100%, with an explicit description for 'reference': 'Exact configured site name or canonical site ID.' The tool description does not add details on how that reference is resolved or provide examples, so the value matches the schema baseline rather than exceeding it.

  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 action and object: 'Inspect one configured site' plus what will be inspected, 'policy claims, and inventory identities.' This clearly distinguishes it from siblings like bourne_site_list or bourne_site_discover, although it doesn't explicitly name the 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 purpose statement implies when to use this tool: to inspect a single configured site by reference. However, it does not explicitly state when to use this over related tools such as bourne_site_discover or bourne_site_policy_claim, leaving the choices up to the model.

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

• bourne_execution_cancelA
  3.7/5.0
  Behavior3/5

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

  Annotations already indicate destructiveHint=true and idempotentHint=false, so the description does not need to repeat those. It adds the important qualifier that only the exact job associated with an existing execution is cancelled, not any arbitrary job ID. This clarifies the scope of destructive behavior and distinguishes from potential misuse. It does not, however, describe side effects like irreversibility or downstream state changes, but the annotations already convey the destructive nature.

  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 that is entirely front-loaded with the action and scope. No filler words, and the critical constraint ('only the exact scheduler job') appears early. The sentence is compact and information-dense without being verbose.

  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?

  With one parameter, an output schema present, and annotations covering destructive and persistence behaviors, the description covers the essential aspects of what the tool does and the scope of its operation. It does not mention prerequisites beyond 'existing execution', but that is implied by 'owned by an existing Bourne execution'. Missing details like error behavior (e.g., what happens if the reference is invalid) are not critical given the output schema likely captures responses.

  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 one required parameter 'reference' with no description and 0% schema coverage. The description implies that 'reference' identifies an existing Bourne execution (since it says 'owned by an existing Bourne execution'), but it does not explicitly state that the parameter is that execution's reference, nor does it explain how to obtain it or its format. The description provides some semantic context but falls short of fully compensating for the missing schema documentation.

  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 specifies a concrete verb ('Cancel'), identifies the exact resource ('scheduler job owned by an existing Bourne execution'), and explicitly contrasts with 'arbitrary scheduler job IDs'. This clearly distinguishes it from sibling execution tools like bourne_execution_get, bourne_execution_reconcile, and bourne_execution_wait, which handle retrieval, reconciliation, and waiting respectively.

  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 the key constraint that only exact scheduler jobs owned by existing Bourne executions are accepted, which implies that cancellation is for executions that are currently active. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention conditions like 'use when you need to stop a running execution'. Such guidance is not present, so the usage context is implied but not explicit.

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

• bourne_execution_waitA
  3.7/5.0
  Behavior3/5

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

  Annotations already convey non-read-only, non-idempotent, non-destructive. The description adds that waiting creates no execution, which is a useful behavioral note, but it does not disclose error behavior, timeout side effects, or what happens if execution is missing. It adds marginal value beyond 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 clauses, concise, front-loaded with the primary action. Every word contributes meaning without repetition.

  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?

  An output schema exists, so return values are covered. However, for a wait tool, the description lacks parameter explanations and usage context, leaving the agent to infer 'reference' and timeout semantics. It is adequate but has clear gaps.

  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?

  With 0% schema description coverage, the description carries the burden. It hints at the optional timeout via 'optional bounded caller timeout', but does not explain what 'reference' refers to or how to format it. The description does not fully compensate for the schema gap.

  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 verb 'wait' and the resource 'existing Bourne-managed scheduled execution', and explicitly notes it creates no execution, distinguishing it from creation tools. It is specific and unambiguous, though it doesn't name sibling 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 description implies use when you need to block on an execution, but provides no explicit when-to-use vs alternatives like bourne_execution_get or bourne_execution_cancel. No mention of when not to use or prerequisites such as initiating an execution first.

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

• bourne_discoverA
  3.8/5.0
  Behavior4/5

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

  All annotation hints are false, so the description is the sole source of behavioral information. It adds useful context: the discovery is bounded/local, a new snapshot is persisted, and the snapshot is immutable, implying no destructive change to existing data. It does not mention auth or rate limits, but for a zero-parameter action this is reasonable.

  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 gives the action, scope, and result. Every word contributes to the meaning.

  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?

  The output schema covers return values and there are no input parameters, which simplifies the context. However, the description leaves the boundary between bourne_discover and bourne_site_discover ambiguous, and the phrase 'bounded local' is not explained, so the agent may still struggle to know when this tool is the right choice.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema already completely captures the input surface. The description therefore has no need to explain parameters, and the baseline of 4 applies.

  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 names a concrete action ('Run ... compute-site discovery') and a concrete outcome ('persist a new immutable inventory snapshot'), so an agent can understand what the tool does. It does not explicitly distinguish itself from the closely named sibling bourne_site_discover, so it misses the top score.

  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 usage context: call it when you want bounded local compute-site discovery and a persisted inventory snapshot. However, it provides no explicit when-not guidance or comparison to alternatives such as bourne_site_discover or bourne_inventory, leaving the decision to inference.

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

• bourne_execute_planA
  3.9/5.0
  Behavior4/5

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

  Annotations already declare destructiveHint=true and idempotentHint=false, so the agent knows this is a destructive, non-idempotent action. The description adds value by clarifying that the plan itself remains unchanged (immutable) and lists what is not altered (command, resources, placement, backend, inventory). This supplements the annotations without contradicting them.

  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, focused sentence that front-loads the primary action and qualifies it with the immutable scope. There is no fluff or redundant phrasing; every word 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 tool has a simple single-parameter interface and an output schema (which presumably describes the result), the description covers the core action well. However, it does not mention side effects or the need for the plan to already exist, which could be inferred from 'persisted'. The presence of sibling tools like bourne_execution_wait and bourne_execution_get partially compensates, but a note about the execution being asynchronous or the need for prior validation would make it more complete. Overall close to complete.

  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 0% description coverage for plan_id, and the description does not explain its format, origin, or constraints. The baseline for a single parameter with no schema coverage is that the description must compensate, but it offers no additional meaning beyond 'plan_id' being an identifier. This is a significant gap for an agent trying to construct a valid request.

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

  Purpose5/5

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

  The description states a specific verb ('Execute') and a distinct resource type ('persisted Bourne plan'), clearly differentiating this tool from siblings like bourne_plan (which creates plans) and bourne_execution_get (which retrieves execution status). The scope is precise: it executes an existing plan without modifying its definition.

  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 have an immutable plan_id and want to run it, but it does not explicitly contrast with alternatives or state when not to use it. There is no explicit guidance on prerequisites (e.g., plan must exist) or when to use related execution tools instead. The context is clear but not explicitly framed.

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

• bourne_planA
  3.9/5.0
  Behavior3/5

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

  The 'never executes the workload' disclosure is genuinely useful behavioral context, and prior hints are absent. However, the description stops short of explaining what 'persist' actually creates or changes, whether repeated calls are safe, and what resolution fulfillment means in terms of lifecycle or side effects.

  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 tightly written sentences that front-load the core action and then add the key non-execution caveat. Every clause contributes meaningful information and no space is wasted.

  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?

  Given the complexity of the nested ExecutionRequest schema and the breadth of sibling tools, the description provides the essential planning-vs-execution distinction but lacks workflow positioning. It does not explain how this tool fits after validation/discovery or before execution, or what the resolved result is used for.

  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 both parameter schemas already document the request and the inventory reference. The tool description adds no additional details about the request structure, inventory_reference semantics, or how properties like 'latest' or '@N' behave.

  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?

  Uses a specific verb+resource ('Persist and resolve an ExecutionRequest v2') and explicitly contrasts planning with execution by saying 'Planning never executes the workload.' This distinguishes it from execution-related siblings without needing to inspect their schemas.

  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?

  Provides clear context for when to use the tool: against an existing inventory, to resolve a request, and specifically without executing the workload. It does not name or explicitly exclude alternatives such as bourne_validate_request, bourne_discover, or bourne_execute_plan.

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

• bourne_inventoryA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare the operation is read-only and idempotent, so the bar is lower. The description adds the key behavioral boundary that no discovery is triggered, which is meaningful because discovery could be a separate, potentially expensive operation and annotations alone do not convey this distinction. No contradiction exists.

  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?

  One focused sentence front-loads the action and the accepted reference identifiers, then appends the crucial 'never performs discovery' caveat. There is no filler, repetition, or additional context that would distract an agent.

  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 one optional parameter, full schema coverage, an output schema, and annotations covering read-only/idempotent/non-destructive behavior, the description sufficiently conveys which reference to pass and demarks the operation's boundary. Return values do not need to be explained because an output schema exists.

  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 input schema has 100% description coverage, so the parameter already carries its meaning. The tool description mostly restates the same reference forms found in the schema and adds little new semantic detail, making the baseline of 3 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 opens with a concrete action and resource ('read an existing inventory') and lists the accepted reference forms (latest, full ID, unique prefix, @N). It further separates the tool from discovery-oriented siblings by stating it never performs discovery, leaving no ambiguity about what this 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 Guidelines4/5

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

  The description makes the intended use clear: retrieve an already-existing inventory by one of several reference types. The explicit 'this never performs discovery' also gives a useful when-not signal against discovery-family tools, though it does not explicitly name those alternatives as replacements.

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

• bourne_site_listA
  4.3/5.0
  Behavior4/5

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

  Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds the value 'non-secret' and 'configured' which clarifies what is included and what is deliberately omitted. It does not describe the return format or error handling, but the output schema likely covers that, and no surprising side effects exist given the read-only annotation.

  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, focused sentence that front-loads the action and scope. Every word contributes: 'List', 'configured', 'non-secret', 'local and SSH site contexts'. No filler or redundant information.

  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 zero-parameter listing tool with a read-only annotation and an output schema, the description provides the essential semantics: it enumerates configured sites, excluding secrets, and distinguishes local vs SSH. The output schema can define the exact structure, so nothing critical is missing. The description is complete for the tool's low complexity.

  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?

  There are zero parameters, so the schema fully covers them vacuously. The description correctly implies no input is needed. It adds the domain-specific constraint about non-secret and SSH contexts, which is useful but not about parameters directly. With no parameters, the description is adequate.

  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 explicitly states the action 'List' and the resource 'configured non-secret local and SSH site contexts'. It clearly distinguishes this from siblings like bourne_site_inspect or bourne_site_discover by specifying the listing scope and the exclusion of secrets. The phrasing is precise and not a tautology.

  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 does not mention when to use this tool over alternatives, nor does it provide exclusion criteria. The intended use as a listing operation is implied by the verb, but no explicit guidance on selecting it among the many sibling tools is given. An agent could infer it is the default for enumerating sites, but that is not stated.

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

• bourne_validate_requestA
  4.3/5.0
  Behavior4/5

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

  The annotations already convey readOnly, idempotent, and non-destructive behavior, but the description adds useful scope context that the annotations to capture: the tool explicitly does not perform discovery, planning, persistence, or execution. It also implies that normalization is a pure transform rather than a stateful pipeline action. The output schema covers the return behavior without needing description repetition.

  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?

  One sentence with a clear verb and object, followed by a compact list of excluded behaviors. There is no filler, no repeated schema information, and the most decision-relevant scope information appears early.

  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 single-parameter validation tool with a full nested schema and output schema, there is enough information for an agent to call it correctly. The description cleanly separates it from the sibling plan, discover, execute, and reconcile tools, and the missing return-format details are unnecessary because an output schema is present.

  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 covers the single request parameter very thoroughly, including all nested ExecutionRequest fields plus its own descriptive string. The description adds little parameter-specific meaning beyond identifying the request type and the action to apply to it. A 100% schema description coverage gives a baseline of 3, and the description does not significantly exceed it or need to.

  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 concrete action, Validate and normalize, and names a specific resource, ExecutionRequest v2. It also distinguishes itself from pipeline steps by explicitly excluding discovery, planning, persistence, and execution, which maps cleanly to sibling tools like bourne_discover, bourne_plan, and bourne_execute_plan.

  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 tool clearly signals when it should be used: whenever an ExecutionRequest needs pre-flight validation or normalization, and it explicitly rules out other pipeline stages. It does not name alternatives explicitly such as use bourne_plan instead when you need planning, but the exclusion list is strong enough not to require much inference.

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

• bourne_request_schemaA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful contextual value by identifying the specific artifact returned—'canonical ExecutionRequest version-2 JSON Schema'—and contains no contradictions.

  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 entire description is one efficient, front-loaded sentence. Every word contributes to the tool's purpose, and there is no redundant phrasing.

  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 simple schema-retrieval tool with no parameters and an existing output schema, the description is complete. An agent knows exactly what it will receive and can invoke the tool without needing additional context.

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

  Parameters4/5

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

  The tool has zero parameters and the input schema has 100% description coverage vacuously, so there are no hidden or undocumented arguments to explain. The description is not required to compensate for missing parameter guidance.

  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 ('Return') with a concrete resource: Bourne's canonical ExecutionRequest version-2 JSON Schema. It is clearly distinct from siblings like bourne_validate_request or bourne_discover because it identifies the exact artifact and version being retrieved.

  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 intended use is clear from the description: fetch Bourne's canonical ExecutionRequest v2 schema. It does not explicitly name alternatives or exclusions, but for a zero-parameter schema-retrieval tool this ambiguity is minimal and the context is strong enough.

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

• bourne_site_candidatesA
  4.5/5.0
  Behavior4/5

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

  Annotations only mark readOnly/openWorld/idempotent/destructive hints as false, which is minimal. The description adds important behavior beyond them: the tool does not execute or durably persist a request/plan, stores an ephemeral candidate session in the MCP process, and loses that session on restart. That is valuable context the annotations alone do not provide.

  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: the first states the tool's purpose and inputs, the second gives pipeline placement and the sibling alternative, and the third discloses persistence/restart effects. Everything earns its place with no filler.

  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 description covers what the tool does, when to use it, when not to use it, and the key side-effect of ephemerality. An output schema exists, so return-value explanation is not required. The only conceptually risky areas (durable persistence, execution) are explicitly addressed.

  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 all four parameters already have documented meaning in the input schema: reference, request, inventory_reference, and provider. The tool description does not add new per-parameter semantics, but it does clarify the overall role of provider constraints and the default inventory flow, which is reasonable given the schema already carries the detail.

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

  Purpose5/5

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

  States a specific verb ('Generate'), an explicit resource ('candidate plans for one configured site'), a bound ('at most 64'), and the key inputs. It also distinguishes itself from bourne_plan by calling out site-aware candidate comparison, so an agent can tell sibling tools apart.

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

  Usage Guidelines5/5

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

  Explicitly says when to use it ('after site discovery and before bourne_site_select') and names the alternative ('use bourne_plan when site-aware candidate comparison is unnecessary'). This gives clear selection logic relative to siblings.

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

• bourne_site_policy_claimA
  4.5/5.0
  Behavior4/5

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

  Annotations already establish this is not read-only and not destructive. The description goes further by disclosing that it appends, stores no source document, fetches no URL, runs no command, and does not modify previous claims. This adds genuinely useful behavioral context beyond the annotation flags.

  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, front-loaded with the core action, and every sentence contributes: what it does, what the parameters mean, when to use it, which sibling to use instead, and what side effects it does not have. No wasted words.

  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 policy-writing tool with a rich input schema and output schema, the description supplies the missing strategic context: durable append semantics, placement before candidate generation, and the distinction from discovery. An agent has enough information to choose and call the tool correctly at a high level.

  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 carries the full semantic weight for both `reference` and `claim`. The description adds a concise restatement of what each parameter contains, but no significant meaning beyond the schema.

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

  Purpose5/5

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

  The description states a specific verb ('Append') and a specific resource ('one durable structured policy claim and provenance record to an existing configured site'). It also names the sibling tool `bourne_site_discover` to make the boundary explicit, so an agent can distinguish this from the discovery workflow.

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

  Usage Guidelines5/5

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

  The description explicitly says to use this tool for 'reviewed site constraints or advice before candidate generation' and directs observation of live infrastructure to `bourne_site_discover` instead. This gives clear when-to-use and alternative routing.

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

• bourne_site_selectA
  4.7/5.0
  Behavior5/5

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

  Annotations only state readOnlyHint=false, idempotentHint=false, and destructiveHint=false; the description carries substantial behavioral context beyond those flags. It discloses that the tool creates a new plan without editing existing plans, that `request_id` and `candidate_id` live in a single session that breaks across server restarts, and that selection fails when required approvals, declarations, or provider trust are missing. There is no contradiction with the annotations—'writes a new plan' is consistent with non-read-only, and 'without editing existing plans' is consistent with destructiveHint=false.

  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 satisfies tasks: a purpose statement, a session prerequisite, write-semantics, a follow-up workflow hint, and failure conditions — all in roughly 70 words. The sentences are front-loaded with purpose, and each sentence provides distinct, non-redundant information. No filler or placeholder text.

  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 schema parameters, an output schema, and a complex workflow position (candidates → select → execute), the description covers a caller's critical needs: where the identifiers come from, how to recover after restart, that no existing plan is modified, the immediate next step to review the plan, and the reasons a selection can fail. The output schema exists, so return-value documentation is not needed in the description. The description is sufficiently complete that an agent can correctly invoke the tool within the sibling chain.

  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 value above the schema by tying `request_id` and `candidate_id` to the same live candidate session in a way the individual field descriptions only implicitly cover, and by explaining the gating conditions for `variant_approvals`, `explicit_user_declarations`, and `trusted_provider_contract` in the degenerate 'selection fails' clause. Since each parameter still has strong schema documentation, the description supplements rather than compensates, moving it to a 4.

  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-plus-resource structure: 'Choose one candidate returned by `bourne_site_candidates`, persist selection evidence, and create a new immutable execution plan without executing it.' It names the exact input source, the action, and the output artifact. It also implicitly distinguishes itself from `bourne_execute_plan` by explicitly stating the plan is not executed, and from `bourne_site_candidates` by stating the candidate is already returned. This is unambiguous 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 Guidelines4/5

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

  The description gives strong usage context: candidates must come from a live `bourne_site_candidates` session, and the plan should be reviewed before calling `bourne_execute_plan`. It also warns to regenerate after a server restart. However, it does not explicitly state when NOT to use this tool or contrast with `bourne_plan`, so the when-to-use framing is strong but lacks an explicit exclusion for alternative planning paths.

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

• bourne_site_discoverA
  4.9/5.0
  Behavior5/5

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

  The description adds substantial behavior beyond annotations: it persists a new immutable snapshot, may require existing SSH user authorization, uses only bounded typed probes, never accepts arbitrary commands, and never executes a scientific workload. These safety and side-effect details are genuinely useful and not present in 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?

  Three sentences compactly cover action, output behavior, parameter meaning, alternative selection, and security constraints. Every sentence adds value, and the core purpose is front-loaded before the comparison with siblings.

  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?

  With one well-documented parameter, an output schema, and strong annotation coverage, the description still covers authorization caveats, behavioral limits, and alternative tool routing. Nothing essential for an agent to decide whether and how to invoke this tool is missing.

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

  Parameters4/5

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

  The schema already fully documents the single 'reference' parameter at 100% coverage, so baseline is 3. The description adds meaningful context by clarifying that reference selects a named local or SSH site and by repeating the exact-name-or-canonical-ID constraint, giving agents better disambiguation than the schema alone.

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

  Purpose5/5

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

  States a specific verb plus object ('Discover one configured site and persist a new immutable inventory snapshot linked to it') and explicitly differentiates itself from siblings by naming bourne_discover and bourne_site_inspect. An agent can immediately tell this is the named-site discovery tool rather than the context-based or inspection tool.

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

  Usage Guidelines5/5

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

  Gives explicit direction: use for a named local or SSH site, use bourne_discover for Bourne's current local context, and use bourne_site_inspect to read existing state. It also warns that SSH discovery may require existing user authorization, giving concrete selection and prerequisite guidance.

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