Server Quality Checklist

Tool Scores

• token_createA
  4.1/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries full burden. It discloses each call produces a unique token, fixed expiry, return structure, and error condition. It explains parameter semantics (resource_type and scope) and mentions downstream usage. However, it does not mention agent existence prerequisites or rate limits.

  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 well-structured: purpose first, then returns, parameter explanations, and integration tips. Each sentence adds value, though it is slightly longer than minimal. It efficiently combines multiple pieces of information without redundancy.

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

  Completeness4/5

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

  Given the tool's complexity and absence of output schema, the description explains the return structure (success and error) and parameter semantics. It mentions integration with sibling tools. However, it lacks details like default expiry duration, whether agent_id must exist, and any authorization requirements. It is fairly complete but not exhaustive.

  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%, but the description adds meaningful context: it explains that resource_type is a free-form string with examples, and scope controls permission level. It also provides usage tips (e.g., 'Pass the full returned token object as token_json to token_validate'), which adds value beyond the schema schema descriptions.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Issue a new HMAC/Ed25519-signed security token for an agent scoped to a resource type and permission level.' It specifies the verb (issue), resource (token), and constraints (scoped to resource type and permission level). It also distinguishes from sibling tools like token_validate and token_revoke by mentioning them in context.

  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 implicitly indicates when to use the tool (to issue tokens), but lacks explicit guidance on when not to use it or comparisons to alternatives like token_validate or token_revoke for other use cases. No preconditions or exclusion criteria are provided.

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

• budget_resetA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description fully bears the transparency burden. It discloses the return values on success and failure, the guard requiring confirm='yes', and the effect of resetting counters while preserving ceiling. 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?

  Three sentences front-load the purpose and return value, then address the error case, and finally give when-to-use advice. No unnecessary words.

  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 covers the operation's effect, return values, failure mode, and usage timing. It lacks details on permissions or side effects beyond the reset, but for a simple administrative tool this is adequate. No output schema exists, so return values are described.

  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%, and the description largely repeats the schema for agent_id and confirm. It adds context about the confirm guard preventing accidental resets, but does not provide additional semantic details beyond what the schema already offers.

  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 'reset' and the resource 'all agent spend counters to zero while preserving the ceiling.' It distinguishes from sibling tools like budget_spend and budget_set_ceiling by specifying the scope and effect.

  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 usage guidance: 'Do not reset mid-task if other agents are actively spending — use only at the start of a new task cycle or after all agents have finished.' It also recommends calling budget_status before and after. However, it does not explicitly list when not to use it or compare to alternative tools, but the guidance is clear for a reset tool.

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

• budget_get_logA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description states 'Read-only — never modifies budget state', which is a clear behavioral disclosure. It also describes success and error return shapes. Missing details like authentication requirements, but for a simple read-only log tool, it is sufficiently 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?

  The description is 3-4 sentences, front-loaded with the core purpose, followed by read-only nature, return shapes, and usage guidance. Every sentence adds value, no filler. Well-structured and concise.

  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 tool's simplicity and absence of output schema, the description covers purpose, behavior (read-only), return format (both success and error), parameter usage, and alternative sibling tool. It is complete for its complexity.

  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% (both parameters have descriptions). The description adds context for limit (default 50 and usage), but for agent_id it only reiterates the schema description ('Calling agent identifier') without clarifying whether it filters results or just identifies the caller. The added value is modest, so baseline 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 clearly states 'Return a chronological list of all token spend transactions' with a specific verb and resource. It also distinguishes itself from the sibling tool budget_status by mentioning 'prefer budget_status for a summary view', which is a clear differentiation.

  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 provides explicit context by stating 'prefer budget_status for a summary view' and 'Useful for auditing which agents consumed the most tokens'. It also gives guidance on the limit parameter with default value. However, it does not explicitly state when not to use this tool, but the alternative is clear.

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

• fsm_transitionA
  4.4/5.0
  Behavior4/5

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

  No annotations, so description carries full burden. Discloses irreversibility, lack of validation, return structures, error conditions, and concurrency warning. Could add auth needs but sufficient.

  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?

  Front-loaded with main purpose. Each sentence adds value, though could be slightly tightened. No waste, but somewhat verbose.

  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 no output schema, description explains return values thoroughly. Covers prerequisites, warnings, and error conditions. Complete for a state transition tool with sibling 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?

  Schema coverage is 100% (baseline 3). Description adds that metadata must be valid JSON and agent_id is for audit, enhancing understanding beyond schema descriptions.

  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 verb 'Advance' and resource 'FSM' are specific. It clearly distinguishes from siblings like orchestrator_info (read) and blackboard_write (blackboard content).

  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 explicit guidance: avoid concurrent transitions, call orchestrator_info first. Warns about missing params and invalid JSON. Lacks explicit when-not-to-use but overall clear.

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

• agent_spawnA
  4.5/5.0
  Behavior4/5

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

  Without annotations, the description carries full burden. It discloses return formats for success and error, lists specific error conditions, and implies async dispatch (on next poll cycle). Lacks details on idempotency or overwrite 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 well-structured sentences with no wasted words. Each sentence serves a distinct purpose: purpose, behavior, usage guidance. Front-loaded with core functionality.

  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 no output schema, the description thoroughly explains return values and error cases. It covers prerequisites, verification steps, and all parameters. Sufficient for an agent to use correctly.

  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 covers 100% of parameters with descriptions. The description adds value by stating the default TTL (3600) and explaining the output structure, which is not in the schema. Good enhancement.

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

  Purpose5/5

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

  The description clearly states the tool dispatches work to a named agent by writing a task record to the blackboard. It uses specific verbs (write, dispatch) and resources (task record, named agent), distinguishing it from siblings like blackboard_write.

  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 advises to call agent_list first to confirm registration and to verify with blackboard_read after spawning. It also lists error conditions. However, it does not explicitly state when not to use this tool versus alternatives like blackboard_write.

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

• budget_set_ceilingA
  4.6/5.0
  Behavior5/5

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

  Discloses return format, immediate effects, consequences of lowering below current spend (denies future budget_spend calls until reset), and that ceiling must be a positive integer. No annotations present, so description carries full burden and satisfies it.

  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?

  Well-structured with clear sentences, each adding value. Front-loaded with purpose and return, then behavioral details. Slightly long but justified given complexity.

  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 no output schema, description fully explains return values. Covers preconditions and runtime implications, making it sufficient for correct agent 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 covers both parameters 100%. Description adds 'total token budget across all agents' and 'audit log' context but does not significantly enhance parameter meaning beyond 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?

  Clear verb-resource pair 'Dynamically change the global token ceiling' distinguishes it from related sibling tools like budget_reset and budget_spend.

  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?

  Explicit warnings: 'Avoid lowering the ceiling while agents are actively running; call budget_status first' and explains when lowering vs raising is appropriate.

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

• budget_statusA
  4.6/5.0
  Behavior5/5

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

  With no annotations, description fully carries the burden. It explicitly states 'Never modifies budget state', describes both success and error response formats, and reveals audit behavior ('agent_id is recorded... does not filter results').

  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?

  Description is compact but packs significant detail: purpose, fields, error case, behavioral nuance, and usage advice. Could be slightly tighter but remains efficient.

  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?

  No output schema, but description provides full return structure. Covers primary use, error handling, audit vs. filter behavior, and contextual usage guidance. Complete for a simple query tool.

  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%, baseline 3. Description adds value by explaining that agent_id is solely for audit logging and does not filter results, which is not obvious from the schema description.

  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 states verb 'Get a read-only snapshot' and specific resource 'global FederatedBudget' with clear fields (ceiling, spent, remaining, per-agent). It explicitly distinguishes from siblings like budget_spend and budget_get_log.

  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?

  Instructions to 'Call before budget_spend to check available capacity' and 'use budget_get_log for a full timestamped transaction history' provide clear usage context. No explicit when-not, but guidance is sufficient.

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

• agent_stopA
  4.7/5.0
  Behavior5/5

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

  Despite no annotations, the description thoroughly discloses behavior: it returns success/error, the stop is not immediate but on next poll, and the reason is logged. This fully compensates for missing 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 concise (four sentences) and front-loaded with the primary purpose. Every sentence adds necessary context without redundancy.

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

  Completeness5/5

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

  For a two-parameter tool with no output schema or annotations, the description covers return format, behavior, prerequisites, and audit logging, providing complete 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?

  Schema coverage is 100%, but the description adds value by linking agent_id to agent_list output and explaining the reason parameter's audit purpose, going 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 clearly states the tool stops an agent by writing a stop record to the blackboard and marking it as stopped in the registry, which distinguishes it from sibling tools like agent_list and agent_spawn.

  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 advises calling agent_list first to confirm the agent is active, which provides clear usage context. It could be improved by explicitly stating when not to use the tool, but the guidance is strong.

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

• audit_queryA
  4.7/5.0
  Behavior5/5

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

  Declares read-only nature upfront. Describes return format on success and failure, including behavior when log file cannot be read. No annotations provided, so description fully covers behavioral expectations.

  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 front-loaded purpose, no wasted words. Every sentence adds value.

  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?

  Describes return format, error conditions, and sibling tool. Covers all 5 parameters with usage context. No output schema needed as return is described inline.

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

  Parameters3/5

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

  Schema coverage is 100%, so baseline is 3. Description adds that filters are optional and combinable, and provides default limit, but does not add significant meaning beyond schema descriptions.

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

  Purpose5/5

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

  Clearly states 'Search the append-only audit log' with optional filters. Distinguishes from sibling tool audit_tail by specifying use case for compliance review and debugging.

  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 contrasts with audit_tail for unfiltered recent entries. Provides guidance on filter combinations and limit usage to avoid large payloads.

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

• blackboard_listA
  4.7/5.0
  Behavior4/5

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

  No annotations provided, so description carries full burden. It declares read-only with no side effects, describes success/error return formats, and notes all non-expired keys returned in one response with performance hint. Lacks discussion of rate limits or access control details, but sufficient for a read operation.

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

  Conciseness5/5

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

  Three sentences, each serving a distinct purpose: purpose+option, safety+return, usage guidance. No fluff. Front-loaded with core action.

  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 no output schema, description explains return values and error case. Covers parameters, use case, and behavior adequately. No missing critical information for correct invocation.

  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% and description reinforces meaning: agent_id for scoped access, prefix for filtering. Adds example usage (e.g., 'task:' prefix) that adds value beyond schema descriptions.

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

  Purpose5/5

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

  The description clearly states the action (list), resource (active keys on shared blackboard), and optional filter (prefix). It differentiates from sibling tool 'blackboard_read' by noting it's for when you don't know the exact key name.

  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?

  Provides explicit when-to-use guidance: 'Use before blackboard_read when you do not know the exact key name'. Also advises on prefix filtering to reduce payload size on large blackboards, and mentions scoped access with agent_id.

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

• blackboard_searchA
  4.7/5.0
  Behavior5/5

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

  No annotations provided, but description discloses read-only nature, semantic vs lexical ranking, return format, and hints to follow up with blackboard_read.

  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?

  Concise, front-loaded with main action, then usage guidance and behavioral details. Each sentence adds value.

  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?

  Despite lack of annotations and output schema, description covers purpose, usage, ranking behavior, return format, and follow-up, making it complete for a tool with 4 parameters.

  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 good descriptions for all parameters. Description adds context about return format but doesn't significantly enhance parameter understanding beyond 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?

  States 'Search the shared blackboard for entries relevant to a query and return the top-K ranked matches', clearly specifying verb, resource, and outcome. Also distinguishes from sibling blackboard_list.

  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 'Use this instead of blackboard_list when you need *relevant* keys rather than *all* keys'.

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

• blackboard_writeA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses behavior: overwriting, TTL replacement, non-idempotent nature (new timestamp/sourceAgent each call), return formats for success and error, required JSON validity, and authentication conditions. This is comprehensive.

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

  Conciseness4/5

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

  The description is a single paragraph that efficiently packs all necessary information. It is front-loaded with the primary purpose and then covers return values, error conditions, and parameter usage. Slightly dense but not verbose.

  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 no output schema, the description covers return values and error conditions. It explains idempotency, TTL behavior, key naming, authentication, and suggests confirmation with blackboard_read. This is complete for a write tool.

  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?

  Despite 100% schema coverage, the description adds value beyond the schema: clarifying that value must be a JSON string (use JSON.stringify), that omitting ttl makes the entry persistent, and that agent_token is only needed for protected keys. It also suggests namespaced keys.

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

  Purpose5/5

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

  The description clearly states the tool writes a JSON value to a key on the blackboard, overwriting existing entries. It uses a specific verb ('write') and resource ('blackboard'), and the action is distinct from sibling tools (e.g., blackboard_read, blackboard_delete).

  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 provides usage guidance such as using namespaced keys and confirming with blackboard_read if the consumer is polling. It does not explicitly compare to other tools, but the write operation is naturally differentiated from read/delete/list. Conditional usage of agent_token is explained.

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

• budget_spendA
  4.7/5.0
  Behavior4/5

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

  With no annotations, description discloses three return cases (success, denied, error) and agent tracking. Could mention authorization requirements, but covers the main behavioral aspects well.

  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?

  Single paragraph packs information efficiently, but could be better structured (e.g., bullet points for return cases). Not overly verbose, though.

  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?

  No output schema, but description explains full return structure, error handling, and prescriptive usage flow. Connects to budget_status sibling, making it complete for safe invocation.

  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?

  Schema coverage is 100%, but the description adds significant context: tokens are the estimated cost of LLM call to be passed before model invocation; agent_id is tracked in spend log and reported by budget_status.

  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 it deducts tokens from a global FederatedBudget on behalf of an agent. It distinguishes from sibling tools like budget_status by explicitly advising to check balance first before spending.

  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?

  Provides explicit guidance: call budget_status first, pass expected usage tokens before invoking model, and never attempt LLM call after receiving allowed:false.

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

• orchestrator_infoA
  4.7/5.0
  Behavior4/5

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

  Discloses that the tool always returns {ok:true} and never fails, and lists the return shape. Without annotations, this is sufficient, though it omits potential latency or auth details (likely irrelevant for this tool).

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

  Conciseness5/5

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

  Two sentences with no fluff: states purpose, return structure, and usage guidance upfront. Every sentence adds value.

  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 tool without output schema, the description provides complete context: health snapshot contents, success guarantee, and recommended usage as first call.

  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?

  No parameters exist, and schema coverage is 100%. Baseline is 4; description adds no parameter info because none are needed.

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

  Purpose5/5

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

  The description clearly states the tool returns a full health snapshot with specific fields (version, config, agent count, etc.). It distinguishes from siblings like config_get and agent_list by positioning itself as a first-call overview 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?

  Explicitly advises using this tool as the first call to confirm server health and discover current config before calling config_get or agent_list. Also notes it always succeeds, guiding error handling expectations.

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

• blackboard_deleteA
  4.8/5.0
  Behavior5/5

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

  Descriptions of all possible return states ({ok:true, deleted:true}, {ok:true, deleted:false}, {ok:false, error:...}) and conditions for token rejection/unavailability are provided. No annotations exist, so description covers behavioral aspects fully.

  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?

  Four sentences, each serving a distinct purpose: purpose, return states, token guidance, and pre-call recommendation. Efficient and clear.

  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?

  Covers return values, token conditions, and pre-check advice. Lacks details on error handling for invalid agent_id, but overall sufficient for a delete operation.

  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% with basic descriptions. The description adds value by specifying key naming format (e.g., 'task:result:q3') and conditional token requirement, which goes beyond 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 clearly states 'Remove an entry from the shared blackboard by key.' The verb 'Remove' and resource 'entry from shared blackboard' are specific, and it distinguishes itself from sibling tools like blackboard_exists, blackboard_read, etc.

  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 advises to 'Call blackboard_exists first to confirm the key is present before deletion.' Also explains when to include or omit agent_token, which guides proper usage.

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

• context_packA
  4.8/5.0
  Behavior5/5

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

  Given no annotations are provided, the description fully discloses behavioral traits: it is read-only ('never modifies the blackboard'), uses relevance ranking with semantic/lexical and recency factors, applies a hard token budget, and auto-excludes expired entries without requiring user action.

  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 comprehensive and well-structured, front-loading the main action and return format. It is not overly verbose, though it could be slightly more concise without losing clarity. Every sentence serves a purpose.

  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 no output schema, the description covers return values explicitly, listing the structure and stating that the 'text' field is ready to use. All key aspects (token budgeting, ranking, excluded entries) are addressed, making it self-sufficient for agent comprehension.

  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%, but the description adds context by explaining how each parameter contributes to the tool's behavior (e.g., 'task' drives relevance ranking, 'agent_id' for scoped access). This reinforces the meaning beyond the schema, earning a score slightly above baseline.

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

  Purpose5/5

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

  The description clearly states the tool assembles a token-budgeted, relevance-ranked context brief from the shared blackboard for a given task. It uses specific verbs ('assemble', 'returns') and distinguishes from siblings like blackboard_list and blackboard_read by emphasizing relevance ranking and token budgeting.

  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 'Use this INSTEAD of blackboard_list + many blackboard_read calls', providing precise when-to-use guidance and alternatives. Also notes read-only nature and automatic TTL exclusion, leaving no ambiguity about appropriate usage.

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

• blackboard_existsA
  4.9/5.0
  Behavior5/5

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

  Declares read-only, no side effects, never modifies state. Describes exact return shapes for success and error, and mentions access checks.

  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?

  Five focused sentences, front-loaded with action and side effects, no redundancy. Each sentence provides essential 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?

  With 2 parameters and no output schema, the description fully covers behavior, parameters, return types, and alternatives. No gaps.

  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 covers basic descriptions (key, agent_id). Description adds key format example and agent_id usage context, enhancing meaning beyond 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?

  Clearly states the tool checks if a key is present and not expired on the shared blackboard. Distinguishes from sibling blackboard_read by noting it's lighter-weight for presence checking.

  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 advises to prefer this over blackboard_read when only checking presence, and specifies key namespace format and agent_id scoping.

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

• blackboard_readA
  4.9/5.0
  Behavior5/5

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

  With no annotations, the description fully covers behavior: read-only, never modifies, specific return structures for found/not-found/unavailable, and scoped access/audit logging using agent_id.

  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 clear, front-loaded purpose. Every sentence adds essential information without redundancy.

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

  Completeness5/5

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

  Given the simple schema and no output schema/annotations, the description is complete: explains returns, errors, usage context, and ties to related tools.

  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%, but the description adds valuable context: key uses namespaced format, agent_id is for scoped access checks and audit logging. This goes beyond the schema's basic descriptions.

  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 it reads a single blackboard entry by key, distinguishing it from siblings like blackboard_list (key discovery) and blackboard_exists (existence check). It explicitly describes the return format for found, missing, and error cases.

  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?

  It provides explicit when-to-use guidance ('Use when you know the exact key') and directs the agent to blackboard_list for key discovery. It also mentions the namespaced key format used across tools.

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

• config_getA
  4.9/5.0
  Behavior5/5

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

  No annotations provided, so description carries full burden. It details return formats for success (single key vs all keys) and error case (unknown key with known keys listed), providing full behavioral transparency.

  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 that are front-loaded with purpose, followed by return types and a usage tip. 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 simple read tool with one optional parameter and no output schema, the description fully explains input, output (including errors), and usage pattern. No gaps.

  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 single optional parameter 'key' is well-described in the schema. The description adds value by explaining the effect of omitting the key (returns all config) and the error message format, though schema already covers basics.

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

  Purpose5/5

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

  The description clearly states the tool reads orchestrator configuration values, can read one or all keys, and differentiates itself from the sibling tool config_set for updates.

  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?

  Explicit guidance: call without key to discover available config names, and refers to config_set for updates. This helps the agent decide when to use this tool vs alternatives.

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

• token_revokeA
  4.9/5.0
  Behavior5/5

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

  Details that revocation is immediate and irreversible, causing token_validate to fail on future attempts. Also mentions audit logging of optional reason. No annotations provided, so description fully covers behavioral traits.

  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?

  Single paragraph with clear, direct statements. Every sentence adds essential information without redundancy. Efficient and well-structured.

  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 tool's simplicity (2 params, no output schema), the description covers return values, side effects, error case, and usage scenarios comprehensively. No gaps.

  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 covers both parameters fully (100% coverage). Description adds context: token_id comes from token_create output, and reason is optional but aids security review, providing value beyond 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 'Permanently revoke a security token by its tokenId' and explains the return values and effects, clearly distinguishing it from sibling tools like token_create and token_validate.

  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 lists when to use: 'when an agent session ends, a permission grant expires by policy, or a token may have been compromised.' Also describes error case when token manager is unavailable.

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

• token_validateA
  4.9/5.0
  Behavior5/5

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

  The description discloses the read-only nature ('Read-only — never modifies token state'), explains the return value structure with specific reasons for failure (invalid_signature, expired, revoked), and covers error cases like invalid JSON. No annotations exist, so the description carries full burden and does so thoroughly.

  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?

  Every sentence is informative and earns its place. The description is front-loaded with the primary purpose, followed by read-only declaration, return details, and usage note. No redundant or vague language.

  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 single parameter and no output schema, the description fully covers all necessary aspects: what the tool does, what it returns, possible reasons for failure, and error handling. It is complete for the tool's 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?

  The input schema has 100% coverage describing token_json as 'JSON-encoded SecureToken object (as returned by token_create)'. The description adds contextual value by explaining how the parameter is used, but the schema already provides adequate meaning, keeping the score slightly below 5.

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

  Purpose5/5

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

  The description clearly states the tool verifies a token's HMAC/Ed25519 signature, expiration, and revocation status. It distinguishes itself from sibling tools like token_create and token_revoke by explicitly mentioning its role as a validation check before granting access.

  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 provides explicit usage guidance: 'Call before granting access to any protected resource' and references token_revoke as an alternative for invalidation. This helps the agent decide when to use this tool versus siblings.

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

• agent_listA
  5/5.0
  Behavior5/5

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

  Declares read-only nature and no side effects. Discloses exact return structure for both success and error cases. No annotations exist, so the description carries full responsibility and meets it well.

  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?

  Four sentences, all valuable. No filler or redundancy. Places the most important information first.

  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 single optional parameter and no output schema, the description covers purpose, usage, behavior, parameter details, and return format comprehensively.

  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?

  Schema has 100% coverage and one parameter. Description adds the valid enum values for status_filter ('active', 'idle', 'stopped', 'error') and explains omission behavior, going beyond the schema's brief description.

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

  Purpose5/5

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

  The description clearly states the action (list all agents) and the resource (agents registered with orchestrator). It distinguishes from sibling tools agent_spawn and agent_stop by advising to call before those operations.

  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 provides when to use this tool: 'Call before agent_spawn or agent_stop to confirm the target agent exists and has the expected status.' Also explains when to omit the filter.

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

• audit_tailA
  5/5.0
  Behavior5/5

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

  No annotations, so description fully covers behavior: read-only, no side effects, return format, error case, and performance guidance for large n.

  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?

  Four sentences, front-loaded with purpose, each sentence adds essential info. No redundancy.

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

  Completeness5/5

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

  Complete for a simple tool: purpose, usage guidance, return format, error handling, parameter semantics all covered. No gaps given absence of output schema.

  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?

  Adds default value, maximum cap, and usage advice beyond schema description. Schema coverage is 100% but description still adds value.

  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?

  Clear verb 'Return' and specific resource 'audit log entries' with ordering detail. Distinct from sibling audit_query as stated.

  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 states when to use (real-time monitoring, quick post-action verification) and when not (filtered searches) with named alternative audit_query. Also notes n cap and default.

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

• config_setA
  5/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses behavior: changes take effect immediately, written to audit log, no undo, and specific return formats including error cases. This is comprehensive and beyond what annotations would 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 sentences, no wasted words. The most important information (action, effect, no undo, return format) is front-loaded. Every sentence adds value.

  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 no output schema, the description covers return values for success and both error cases. It references sibling config_get for pre-step. Parameters are thoroughly explained. The tool is a simple write operation, and the description is complete.

  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 schema coverage is 100%, the description adds concrete examples for 'key' (e.g., 'maxParallelAgents') and explains JSON-encoding for 'value'. It also clarifies error responses for unknown keys or invalid JSON, adding significant meaning.

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

  Purpose5/5

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

  The description clearly states the tool updates a live orchestrator configuration at runtime. It uses a specific verb ('Update') and specifies the resource ('configuration value'). It distinguishes from sibling config_get by advising to call config_get first.

  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 advises to call config_get first to read and confirm key name, providing a clear when-to-use guideline. Also warns about immediate effects, no undo, and audit logging, setting expectations for usage context.

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