Server Quality Checklist

Tool Scores

• pilot_inboxA
  3.6/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden. 'List' implies a read-only operation, but the description adds no further behavioral context such as whether messages are marked as read, how 'recent' is defined, sorting, or pagination. This is a minimal disclosure beyond the verb itself.

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

  Conciseness5/5

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

  The description is two concise sentences with no filler. The first sentence states the action and resource; the second provides usage context. Every word contributes to understanding, and it is appropriately front-loaded.

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

  Completeness4/5

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

  For a simple tool with one parameter and no output schema, the description covers the main purpose and usage. It does not detail the message structure or return format, but 'List recent messages' implies a list return. The omission of alternative tool differentiation (e.g., pilot_received) is a minor gap, but overall it is sufficient for a tool of this 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% for the single 'limit' parameter, so the baseline is 3. The description adds no additional meaning about the parameter, merely restating that it lists 'recent messages', which is already implied by the schema. No extra parameter semantics are provided.

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

  Purpose4/5

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

  The description clearly states that the tool 'List recent messages received from peers and specialists', using a specific verb and resource. It differentiates from siblings by focusing on 'messages received' rather than broader search or send operations, though it doesn't explicitly distinguish from the similarly named 'pilot_received'.

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

  Usage Guidelines4/5

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

  It provides explicit guidance with 'Use this to read async A2A replies', telling the agent when to use this tool. It does not mention alternatives or exclusions, but the intended use case is clear enough for an agent to make a reasonable selection.

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

• pilot_rejectA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It discloses that the peer is notified with the reason, which is useful. However, it does not mention whether the action is reversible, what state changes occur to the pending request, or any permission requirements, leaving gaps for a mutating action.

  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 concise sentences, each earning its place. The first states the action and effect; the second gives the usage context. No redundant wording or fluff.

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

  Completeness4/5

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

  The tool is simple with only two parameters and no output schema. The description covers the core purpose, trigger, and peer notification. It is complete enough for an agent to invoke correctly, though it could mention the fate of the pending handshake (e.g., whether it is removed).

  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 both 'target' and 'reason' are already well documented in the input schema. The description adds minimal extra meaning beyond referencing the reason, 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 uses a specific verb ('Reject') and resource ('pending inbound handshake'), clearly distinguishing it from sibling tools like pilot_approve or pilot_handshake. The scope is unambiguous.

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

  Usage Guidelines4/5

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

  The description explicitly states when to use the tool: 'Use when an unknown agent has requested trust and the user does not want to grant it.' It does not name alternatives explicitly, but the context makes the distinction clear from siblings like pilot_untrust or pilot_approve.

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

• pilot_helpA
  4.1/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses what the output will contain ("The reply describes the supported commands and filter parameters") and implies a read-only nature via "Fetch." However, it does not explicitly state side effects or permissions, though for a help tool these are minimal. Still, it adds some context beyond the name.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core action, and every word earns its place. It is concise without sacrificing clarity.

  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 tool with one parameter and no output schema, the description fully covers purpose, usage context, and expected return content. It is sufficiently complete given the tool's low complexity and sibling context.

  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% coverage, with the single parameter 'agent' described as "Specialist hostname... or peer hostname." The description adds no additional meaning beyond restating that it's for a specialist or peer, so it meets the baseline without enhancing parameter understanding.

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

  Purpose5/5

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

  The description clearly states the tool's function: "Fetch the /help schema for a specialist or peer." It uses a specific verb (fetch) and resource (help schema), and distinguishes itself from siblings by explicitly relating to pilot_query ("before calling pilot_query").

  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 when-to-use guidance: "Use this to learn what /data filters the specialist accepts before calling pilot_query." It doesn't explicitly mention when not to use or name alternative tools, so it stops short of a 5, but provides clear contextual usage.

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

• pilot_pingA
  4.1/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of disclosing behavior. It explains the ping action and RTT return, but does not explicitly mention safety (e.g., non-destructive, read-only) or any side effects. Adequate for a simple diagnostic tool, but lacks explicit safety profile.

  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, with three sentences that front-load the purpose, then mention usage context. No redundant information, every sentence serves a purpose.

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

  Completeness4/5

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

  For a simple diagnostic tool with no annotations and no output schema, the description covers purpose, when to use, and return value. It could mention error behavior or prerequisites, but given the low complexity, it is fairly 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 description does not add any parameter-specific information beyond the schema. Schema covers count and target with descriptions, but timeout_seconds lacks description, and the tool description does not compensate. Since schema coverage is 67%, the description should add some context but doesn't.

  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 performs a round-trip ping to confirm tunnel connectivity and returns RTT. It uses a specific verb ('ping'), identifies the resource ('peer'), and the outcome is measurable, distinguishing it from siblings like pilot_send and pilot_query.

  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 this tool: 'Use when pilot_send / pilot_query / pilot_send_file are failing' to isolate reachability vs message-layer issues. It names alternative tools, providing clear exclusion criteria.

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

• pilot_handshakeA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals important traits: trust is bilateral, propagation has a seconds-to-a-minute delay, and immediate send attempts may fail. This goes beyond what the schema or annotations capture, though it does not cover edge cases like repeated handshakes or revocation.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core purpose, then adds the most critical operational caveats (approval types and propagation delay). Every sentence earns its place; there is no fluff or repetition of schema content.

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

  Completeness4/5

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

  Given the tool's moderate complexity, no annotations, and no output schema, the description covers the essential usage scenario: what it does, target types, approval behavior, and a practical troubleshooting tip. It lacks detail on the response format or what happens if the target is already trusted, but these are minor gaps for a handshake tool.

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

  Parameters3/5

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

  Schema coverage is 100%, so the baseline is 3. The description does not add parameter-level details beyond the schema; it mentions "target" in context (catalog specialists vs human peers) and the reason field is only implied as part of the approval flow. The schema's property descriptions already fully define both parameters.

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

  Purpose5/5

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

  The description clearly states the tool's function: "Initiate bilateral trust with a peer or specialist." This is a specific verb+resource combination that distinguishes it from sibling tools like pilot_trust_check (which checks trust) and pilot_approve (which approves requests). It also names concrete target examples and clarifies the trust relationship.

  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 strong usage context: it explains that catalog specialists auto-approve while human peers require manual approval, and it offers a practical retry instruction if pilot_send fails after a handshake due to propagation delay. It does not explicitly name alternatives or when not to use the tool, but the guidance effectively directs the agent on when and how to use it.

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

• pilot_peersA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It states the operation is a listing (read-only) and discloses the returned data fields (tags, last-seen timestamps). It does not detail edge cases or output formatting, but for a zero-parameter list tool this is sufficient and non-misleading.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that states the action, the target resource, and the included details. Every word contributes meaning; there is no filler or repetition.

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

  Completeness4/5

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

  For a tool with no parameters, no output schema, and no annotations, the description adequately covers what the tool returns and the condition ('currently connected'). It lacks explicit statements about empty results or live vs. cached data, but these are not critical for such a simple listing 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?

  The tool has zero parameters, so the description does not need to explain schema fields. The input schema is empty and 100% covered by the absence of parameters, making parameter semantics inherently clear.

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

  Purpose5/5

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

  The description uses a specific verb ('List') and explicitly names the resource ('currently connected peers') with the output scope ('tags and last-seen timestamps'). It clearly distinguishes from sibling tools like pilot_find or pilot_ping, which are not about listing the current connection set.

  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 use case: call this tool when you need to see which peers are currently connected and their metadata. However, it does not explicitly state when not to use it or compare it with alternatives such as pilot_find or pilot_lookup, leaving the usage context implicit.

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

• pilot_send_fileA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It discloses the trust requirement and delivery mechanism (recipient finds via pilot_received). Could add error/edge-case behavior (e.g., non-trusted peer handling), but the provided behavioral details are meaningful and valuable.

  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: main purpose, common uses, and prerequisite. Front-loaded, zero fluff, every sentence serves a distinct function.

  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 the workflow, trust prerequisite, and recipient discovery. For a two-parameter tool with no output schema, this is adequate. Missing error behavior or return details, but not critical given simplicity.

  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 100% of parameters with clear descriptions, so baseline 3 applies. The tool description adds no additional parameter semantics beyond what the schema already provides.

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

  Purpose5/5

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

  Clearly specifies verb (send), resource (local file to peer), and context (Pilot overlay). Mentions recipient discovery via pilot_received, distinguishing it from generic send/broadcast tools. Common-use examples (code patch, dataset, artifact) further clarify intent.

  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 common use cases and explicit prerequisite (trust via handshake and approval). Does not explicitly state when not to use or name alternatives, but the references to pilot_received and handshake imply file-transfer-specific usage. Strong context but lacks explicit exclusions.

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

• pilot_untrustA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the effect of revoking trust (messages and file transfers fail) and that the action is reversible via trust re-establishment. This goes beyond the schema and gives important side-effect context.

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

  Conciseness5/5

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

  The description is concise and well-structured: the first sentence states the primary action, the second adds consequences and usage context. No filler or redundancy.

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

  Completeness4/5

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

  For a simple one-parameter tool without an output schema, the description covers what it does, when to use it, and the behavioral outcome. It doesn't mention edge cases like attempting to revoke trust from a peer that is already untrusted, but the core context is complete.

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

  Parameters3/5

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

  The schema already provides a description for the single parameter 'target' (100% coverage), so the description does not need to add parameter semantics. The baseline of 3 applies because the description adds no extra meaning beyond what the schema already states.

  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 ('Revoke an existing trust relationship') and identifies the resource ('a peer'). The verb 'Revoke' is specific and distinguishes this from sibling tools like pilot_approve or pilot_reject, which deal with different trust states.

  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 when-to-use scenarios ('compromised, retired, or no longer wants to receive their messages') and explains the consequence (send-message/file transfer fail until trust re-established). It does not explicitly name alternative tools, but the context is clear enough for an agent to select it appropriately.

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

• pilot_approveA
  4.3/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the full burden. It clearly states the action ('Approve a pending inbound handshake') and adds the delegation nuance, but it does not disclose side effects, reversibility, or authorization requirements. For a simple approval action, the core behavior is transparent, but additional behavioral context (e.g., what changes after approval) is missing.

  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, front-loaded with the action and immediately followed by a valuable usage exception. No filler or 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?

  With one simple parameter, no output schema, and a straightforward action, the description fully covers the tool's purpose, usage constraints, and the distinction from CLI-based approval. The sibling tool list further situates it. No critical context is missing.

  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 includes a single 'target' parameter with a description ('Pending peer hostname, node_id, or address.'), covering 100% of the parameter. The description adds no additional meaning beyond the schema, so the baseline score of 3 applies.

  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 ('Approve') tied to a clear resource ('pending inbound handshake'), and contrasts with the CLI alternative, distinguishing it from sibling tools like pilot_reject or pilot_handshake. The scope is well-defined.

  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 both a positive condition ('only auto-call this tool when the user has explicitly delegated trust decisions') and a negative one ('Most handshakes are user-driven and should be approved via pilotctl approve directly'), naming the alternative. This is exemplary usage guidance.

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

• pilot_lookupA
  4.3/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the output fields and the general lookup behavior, but does not mention potential failure modes, whether it is read-only (though 'lookup' implies so), or any edge cases like missing nodes. The description adds some context but lacks richer behavioral detail.

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

  Conciseness5/5

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

  The description is two concise sentences. The first sentence states the purpose and expected output, the second provides usage context and sibling differentiation. Every word earns its place with 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?

  For a simple lookup tool with one parameter and no output schema, the description adequately covers purpose, return fields, and usage context. It even compares itself to a sibling tool, ensuring the agent has sufficient context to decide when to invoke it.

  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 already provides 100% coverage for the single parameter 'target' with a clear description of accepted formats. The tool description does not add any additional parameter semantics, so the baseline score of 3 is appropriate given the high schema coverage.

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

  Purpose5/5

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

  The description clearly states the tool does a 'Registry lookup for a node' and explicitly lists the return fields (public key, listen address, hostname, last-seen timestamp, tags). It distinguishes from the sibling tool pilot_find by noting it is 'More detailed than pilot_find', making the purpose and scope highly specific.

  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 guidance on when to use the tool: 'Use when you need to verify a peer's registered identity or check their last activity.' It also implicitly differentiates from pilot_find by pointing out it is more detailed, which helps the agent choose between alternatives.

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

• pilot_pendingA
  4.3/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses that entries are typically from human-operated peers and that they are inbound and pending approval, which adds context. However, it doesn't explicitly state that the operation is read-only or describe any side effects, though the verb 'List' implies a safe read. The information is sufficient for a low-risk tool but not richly 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 two sentences long, front-loaded with the primary purpose, followed by pairing suggestions and contextual note. Every sentence adds value, with no fluff or repetition.

  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 low complexity (no params, no output schema), the description is complete. It states what the tool lists, why those items appear (human peers), and how to act on them (approve/reject). This fully covers the likely use case without needing return-value details.

  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 fully covers everything (100% coverage). The description doesn't need to explain parameters, and it doesn't. This is the appropriate baseline score.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'List inbound handshakes waiting on your approval.' This is a specific verb + resource + scope, and it distinguishes itself from sibling tools by focusing on pending handshakes rather than general find/lookup/search operations.

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

  Usage Guidelines4/5

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

  It provides clear context on when to use this tool: to see handshakes awaiting manual approval, and it explicitly pairs with pilot_approve and pilot_reject as next steps. It also mentions that most service agents auto-approve, giving helpful situational context. However, it doesn't explicitly state when not to use it or name alternatives.

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

• pilot_broadcastA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It discloses a key behavior: broadcasts only reach trusted peers, and untrusted peers silently drop the message. This is valuable context beyond a simple 'broadcast' definition.

  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-loaded with the main action, followed by use cases and a trust caveat. Every sentence adds value; no filler or redundancy.

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

  Completeness4/5

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

  For a broadcast tool with no output schema, the description is sufficiently complete for selection and invocation. It covers purpose, usage scenarios, and a critical trust-related behavior. It doesn't explain return values, but that is not necessary given the lack of an output schema and the straightforward action.

  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 descriptions for both parameters, so the baseline is 3. The description adds meaning by naming the default network ('The default data-exchange network is "9"'), which helps with network_id selection beyond the schema's generic example.

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

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb and resource: 'Broadcast a message to every peer in a Pilot network.' It distinguishes from sibling tools like pilot_send by emphasizing 'every peer' as the broadcast scope.

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

  Usage Guidelines4/5

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

  It provides common use cases ('announce a capability, request collaborators, publish a status update') that clarify when to use broadcast. It doesn't explicitly mention alternatives or when not to use it, but the 'every peer' wording implicitly separates it from point-to-point tools like pilot_send.

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

• pilot_publishA
  4.4/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden. It discloses that subscribers receive messages asynchronously, that the operation requires trust, that it uses the same authenticated tunnel as send-message, and that it will fail on untrusted peers. These are meaningful behavioral traits beyond just the tool's existence.

  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: two sentences plus a trust warning. It front-loads the main purpose and includes the most important usage detail (trust requirement) without any filler. Every sentence serves a distinct purpose.

  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 simplicity (3 flat string params, no output schema) and strong annotation-free behavioral context (async, trust), the description is largely complete. It could be more complete by noting the return behavior (e.g., it returns success/failure immediately) or whether messages are persisted, but these are minor gaps for a pub/sub publish operation.

  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% coverage, with clear descriptions for peer, topic, and message. The description does not add additional parameter-level meaning, so the baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description opens with a specific verb+resource: 'Publish a message to a topic on a peer's pub/sub channel.' It clearly distinguishes the publish action from siblings like pilot_subscribe (which receives) and pilot_broadcast (which likely fans out to all peers). The example of publishing 'build-complete' further anchors the tool's role.

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

  Usage Guidelines4/5

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

  The description explicitly states when to use: 'Use for event-driven agent coordination' with a concrete example. It also gives a critical prerequisite: 'call pilot_trust_check(peer) first.' However, it does not explicitly mention when not to use it or name alternatives such as pilot_broadcast or pilot_send for other messaging patterns, so it falls short of a 5.

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

• pilot_queryA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses key behavioral traits: reply format is JSON, replies over ~8 KB get truncated mid-stream, and a 'limit' can mitigate this. It also implies the tool relies on specialist-specific /help documentation, which sets expectations. Minor gaps include error handling or auth requirements, but the most critical behaviors are covered.

  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—three sentences—and front-loaded with the primary purpose. Each sentence adds distinct value: the core action, the prerequisite help step, the truncation caveat with a mitigation, and the alternative tool. No filler or redundancies.

  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 two parameters (one nested object) and no output schema, the description is remarkably complete. It covers the primary use case, the prerequisite step, the large-reply truncation behavior, and the alternative for digests. The absence of an output schema is compensated by the explicit 'Reply is JSON' statement.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining the 'limit' usage inside filters, mentioning the default empty query '{}', and tying filter parameters to the specialist's /help reply. This provides context that the raw schema does not convey.

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

  Purpose4/5

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

  The description clearly states the tool 'Query a specialist for structured data using its /data command', identifying the specific verb, resource, and mechanism. It distinguishes from siblings by mentioning pilot_summary as an alternative for digests, though it doesn't explicitly contrast with other query-like tools like pilot_find or pilot_lookup.

  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 when-to-use guidance: 'Use pilot_help first to learn what filter parameters it accepts' and 'For digests of large datasets, use pilot_summary instead.' It also instructs on handling large replies by passing a 'limit' inside filters, giving clear actionable direction.

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

• pilot_receivedA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the storage location (~/.pilot/received/) and the destructive behavior of clear=true ('purge after processing'). This is meaningful transparency for a potential delete operation, though it doesn't mention other side effects or output format.

  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, front-loaded with the primary action, then relevant details. Every word earns its place: 'List files received from peers (~/.pilot/received/)' is efficient, and the second sentence packs the companion tool and parameter behavior without fluff.

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

  Completeness4/5

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

  For a tool with one optional parameter, no output schema, and no annotations, the description is reasonably complete. It covers the action, location, and parameter behavior. However, it doesn't mention the return format (e.g., list of file names), which would be helpful but isn't critical given the tool's simplicity.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the parameter's purpose beyond the schema: 'Pass clear=true to purge after processing' provides semantic context that the schema's 'Purge after listing' doesn't fully convey—specifically that purging is intended after processing the files.

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

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb and resource: 'List files received from peers (~/.pilot/received/)'. It also differentiates from siblings by mentioning the directory path and its companion tool 'pilot_send_file', making it distinct from other pilot_* tools.

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

  Usage Guidelines4/5

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

  The description provides clear usage context: it tells the user to pair with pilot_send_file and explains when to use the clear parameter ('Pass clear=true to purge after processing'). It doesn't explicitly mention alternatives or exclusions, but the pairing reference gives enough guidance for a simple list tool.

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

• pilot_subscribeA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses blocking behavior (blocks until count or timeout), the trust requirement (call pilot_trust_check first), and the purpose of collecting messages. It does not detail timeout return behavior or error conditions, but covers key operational 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?

  Three concise sentences with no fluff. First sentence states the action, second gives use case, third explains blocking and prerequisite. All information is essential and well-structured.

  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 is sufficient for a 4-parameter tool with no annotations or output schema. It covers purpose, behavior, and use case. It does not explicitly state return format, but 'collect N published messages' implies the return value. Error handling and edge cases are not covered, but this is acceptable given 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?

  Schema coverage is 100%, so baseline is 3. The description adds semantic value by linking 'count' to 'collect N' and 'timeout_seconds' to 'until timeout', and gives concrete example topics. It also explains the 'peer' parameter requires prior trust, which is not in 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 subscribes to a topic and collects N messages, which is a specific verb+resource. It distinguishes from siblings like pilot_publish and pilot_broadcast by focusing on the receiving/collecting side of pub/sub.

  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 for event-driven coordination with examples like 'deploy-ready' and 'task-done'. It implies this is the tool to wait for peer signals, but does not explicitly name alternatives or exclusion cases.

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

• pilot_summaryA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries full burden and does well: discloses latency (10-30s), retry on timeout, prose output, and truncation avoidance. It lacks deeper context like auth or rate limits, but the provided behavioral expectations are valuable and specific.

  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, front-loaded with the core purpose, and every clause adds value. The structure efficiently covers purpose, use cases, and key behaviors 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?

  The tool has meaningful complexity (latency, retry, truncation, output format) and the description covers these well. It lacks an example of the prose output or handling of specialist-specific quirks, but for a summary tool it is sufficiently complete.

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

  Parameters3/5

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

  Schema coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema; it merely implies 'question' is used to guide synthesis but this is already in the schema. The description does not enrich parameter understanding.

  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 an LLM-synthesized digest from a specialist, explicitly distinguishing it from raw /data and contrasting with pilot_query's truncation. The verb 'Get' and resource 'digest' are specific, and the sibling differentiation is strong.

  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 explicitly says 'Use when you need a single answer from a large dataset' and names the alternative pilot_query, explaining why (truncation). This gives clear when-to-use and exclusions, making it a model of guidance.

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

• pilot_searchA
  4.7/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and does well: it reveals the LITERAL TOKEN MATCH behavior, emphasizes avoiding phrases, and describes the returned list format. It also sets expectations for the next steps in the discovery process.

  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-loaded with the core purpose, then usage details and workflow. No redundant 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?

  For a simple 2-parameter tool with no output schema, the description covers purpose, matching behavior, return format, and the follow-on workflow (pilot_help, pilot_query). This is complete enough for an agent to select and use the tool effectively.

  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 describes both parameters (100% coverage), so the baseline is 3. The description adds valuable semantics by explaining the literal token matching for the keyword parameter and providing concrete examples, which enhances the schema's 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 states the tool's function with a specific verb ('Search') and resource ('Pilot Protocol directory of 435+ specialist agents'), and clarifies the matching mechanism. This clearly distinguishes it from sibling tools like pilot_find or pilot_lookup.

  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 on how to use it (use single short generic words, not phrases) and a sequential workflow ('After this, call pilot_help... then pilot_query'). However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of the highest standard.

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

• pilot_trust_checkA
  4.7/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool is 'Cheap and idempotent — call freely,' disclosing cost and side-effect profile, and explains the auto-approve behavior for backbone specialists. This gives the agent clear safety and reliability 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?

  The description is highly concise and front-loaded. Each sentence earns its place: the first states the action and usage context, the second explains the underlying requirement, the third covers edge cases, and the fourth gives operational advice. No filler or redundant detail.

  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 one-parameter check tool, the description is remarkably complete. It explains when to use it, why it matters, special cases, and cost/idempotency. The schema covers the parameter fully, and the description's mention of 'trust state' and 'auto-approve' provides sufficient understanding of the return semantics even without an output schema.

  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 already provides a complete description of the 'target' parameter (100% coverage), including its types and the special auto-approve behavior. The main description adds little beyond the schema, merely reinforcing that it can be a peer or specialist, so no extra semantic value is contributed.

  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: 'Check the current trust state with a peer or specialist' and immediately ties it to a specific workflow ('BEFORE calling pilot_send / ...'). It distinguishes itself from sibling tools by being a pre-flight check rather than an action, and it is 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 Guidelines5/5

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

  The description explicitly tells when to use it: before any sending, publishing, broadcasting, or subscribing. It explains why it is necessary (bilateral trust, failure without trust) and provides contextual guidance for backbone specialists vs. human peers, implicitly directing the agent to use pilot_handshake when explicit handshake is needed.

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

• pilot_findA
  4.8/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden. It discloses the DNS-like lookup behavior, the prerequisite of knowing the hostname, and the return condition. It does not mention error behavior or side effects, but this is sufficient for a simple lookup 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?

  Three sentences, front-loaded with the primary purpose, followed by return behavior, a key note, and an alternative usage. 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 one-parameter lookup tool with no output schema, the description covers purpose, usage, alternatives, and parameter meaning. It is complete and self-contained.

  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?

  The schema describes only 'hostname' with type string and 0% coverage. The description adds semantic meaning by stating the lookup is by hostname, making it clear this is the peer's hostname. This fully compensates for the lack of 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?

  Description uses a specific verb ('look up') with a clear resource ('peer by hostname') and explicitly states the return value ('pilot address if found'). It distinguishes from sibling tools by contrasting with pilot_send for capability discovery.

  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: use when you know the hostname, and specifically directs users to pilot_send for capability-based discovery with a concrete example. This is clear when-to-use and when-not-to-use guidance.

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

• pilot_sendA
  4.9/5.0
  Behavior5/5

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

  No annotations are present, so the description carries full responsibility. It discloses the critical behavioral trait that trust is required, states that send 'WILL fail with a connection error' for untrusted or one-way states, and tells where replies land ('pilot_inbox'). This goes beyond a generic send operation and reveals failure modes and async behavior.

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

  Conciseness5/5

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

  The description is three sentences, front-loaded with the main action, then the key exclusion, then the trust prerequisite and reply behavior. Every sentence adds distinct value with zero fluff or repetition. It is rich but compact.

  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 messaging tool with a trust prerequisite and potential failure modes, the description covers the action, target, message format, preconditions, failure behavior, and reply location. It also names alternatives appropriately. No output schema exists, but the description tells where the reply goes, which is sufficient for the agent to use the tool 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?

  Schema coverage is 100% with descriptions for all three parameters, so the baseline is 3. The description adds important semantic context beyond the schema: it emphasizes that 'message' expects natural language rather than /data commands, and that the peer should be a 'known peer'. It also connects wait_seconds to the reply destination via pilot_inbox, enhancing understanding.

  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 sends a plain-text message to a known peer, using a specific verb and resource. It explicitly distinguishes from directory specialists and other sibling tools by saying 'NOT a directory specialist' and 'Use this for A2A messages to human-operated agents and bespoke peers.'

  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 this for A2A messages to human-operated agents and bespoke peers.' It also names exclusions and alternatives: directory specialists need pilot_search/pilot_help/pilot_query for the /data verb pattern. Additionally, it gives a mandatory prerequisite: call pilot_trust_check(target) first, with clear failure consequences.

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