Server Quality Checklist

Tool Scores

• get_agentA
  4.4/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 the return data (profile, ratings, success rate, routing) and implies no side effects. While it could mention error handling or rate limits, the description is adequate for a simple fetch 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?

  Two sentences with no wasted words. The first sentence defines the core purpose, and the second provides actionable usage guidance. Every sentence adds value.

  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 fetch tool with one parameter and no output schema, the description covers purpose, usage, and output contents. It could mention potential errors or that the parameter is required, but overall it is sufficient.

  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?

  Only one parameter (agent_id) exists with 0% schema description coverage. The description does not elaborate on the parameter beyond its name, but the parameter is self-explanatory. However, given the lack of coverage, the description should provide more detail (e.g., format, constraints).

  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 fetches a full agent profile and includes specific details like ratings, success rate, and routing details. It distinguishes itself from sibling tools like list_org_agents (listing) and match_agents (matching).

  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 advises using this tool after match_agents to inspect an agent before transacting, providing clear context and an alternative scenario.

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

• rotate_agent_keyA
  4.4/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses behavioral traits: the old key's invalidation timing, the current temporary behavior (never returns agent_key directly, returns claim_link), auth requirements, and specific HTTP error conditions. This goes beyond what structured fields could convey.

  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 structured into labeled sections (Auth, TEMPORARY, agent_id, Returns) and is front-loaded with the main purpose. While moderately long, each sentence serves a purpose, such as explaining auth or error behavior.

  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?

  Even without an output schema, the description explains what the response contains (claim_link and agent_key: None) and all error conditions (400, 404, 429). It also covers auth setup and the temporary change, making it contextually complete for this 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 single parameter agent_id is only described as 'the agent whose bearer key to rotate,' which adds little beyond the schema's property name and type. Given 0% schema coverage and a single self-explanatory parameter, the description provides minimal value, so a score 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 action ('Request rotation of an agent's bearer key') and clarifies the effect (old key stops working). It also references claim_bearer_key, which distinguishes this tool from the claiming step and sibling tools like set_agent_key.

  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 context on when rotation is appropriate (to invalidate a previous key) and explicitly points to claim_bearer_key for the next step. It also covers auth prerequisites and error cases. However, it does not explicitly contrast with set_agent_key or other siblings, so it's not a full usage guide.

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

• list_org_agentsA
  4.5/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 that the tool returns all agents including unverified ones and explains authentication requirements (X-API-KEY header vs. AIDRESS_API_KEY env var). While it doesn't mention pagination or error behavior, the read-only nature is evident from the verb 'list,' and the extra context adds value beyond mere naming.

  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 purpose statement. The second sentence provides necessary setup instructions, and the third clarifies return scope. Every word earns its place; there is no redundancy or fluff.

  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 (no parameters, no output schema), the description is remarkably complete. It covers purpose, authentication method, scope, and the nuance of including unverified agents. This is sufficient for an agent to correctly invoke the tool without additional assumptions.

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

  Parameters4/5

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

  The tool has zero parameters, and the schema coverage is 100% (empty properties). The baseline for 0 parameters is 4, and the description doesn't need to add parameter details since there are none. It doesn't contradict or duplicate any schema information.

  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 begins with a specific action ('List') and resource ('agents registered under your org API key'), clearly distinguishing it from sibling tools like get_agent (single agent) and list_registry (likely different scope). It further clarifies the scope with 'all agents belonging to your organisation, including unverified ones.'

  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 context for when to use this tool—when you need to list all org agents—and includes specific authentication instructions for both remote and local setups. However, it does not explicitly name alternatives or state when not to use it, so it lacks the 'explicit when/when-not' of a 5.

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

• register_agentA
  4.5/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 delivers richly: it discloses that agent_key is never returned directly (always a claim_link), that an org key auto-verifies at trust_score=70 vs 40 pending review, that price_schedule mismatches are flagged for manual review, that GET flattens payloads to query params, and the full HTTP 202 capability_confirmation_required flow. These are non-obvious behaviors an agent could not infer from the schema.

  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 long but well-organized with clear sections (Required, Conditionally required, Common optional, Less common) and front-loaded purpose. The price_schedule paragraph is somewhat verbose, but the structural delegation of advanced fields to protocol_reference avoids even more bloat. Every section earns its place given the 25-parameter complexity.

  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 highly complex tool with no output schema and no annotations, the description is remarkably complete: it covers conditional requirements, key-handling flow, trust-score side effects, payment validation, and the two-step capability confirmation edge case. Minor gaps include the absence of a full 200-success response shape (beyond claim_link) and no explicit error-case handling, but overall the burden is mostly satisfied.

  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 0%, so the description compensates heavily: agent_id, capabilities (with weight limits), endpoint_url, protocol, settlement_rail, message_protocol, http_methods, price_schedule, and payment fields all receive meaningful semantics beyond bare names, including examples. Gaps remain: candidate_matches is never mentioned, capability_confirmations is only implied by the 202 flow, and the seven 'less common' fields are listed by name with semantics deferred to protocol_reference.

  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 opening sentence 'Register a new AI agent (or human) with the Aidress trust registry' uses a specific verb and resource, and 'new' clearly distinguishes this creation tool from siblings like update_agent, verify_agent, and list_org_agents. The conditional requirement explanations (one agent per org_domain) further pin down its exact 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 gives strong contextual usage guidance: it marks agent_id as required, explains when org fields become conditionally required (when endpoint_url is set), and explicitly routes follow-up actions to claim_bearer_key and protocol_reference('register_advanced_fields'). However, it never explicitly contrasts this tool with alternatives like update_agent or import_agent, so some when-not-to-use guidance is missing.

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

• update_agentA
  4.6/5.0
  Behavior5/5

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

  With no annotations provided, the description fully bears the transparency burden. It discloses authentication requirements in detail, explains why per-call key parameters are absent, notes the sandbox-only constraint for pull_from_agent_id, specifies validation rules (unknown keys return 422), and states the return value. This is exemplary behavioral transparency for a mutation tool.

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

  Conciseness4/5

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

  The description is long but well-organized: a two-sentence core behavior summary, followed by a clearly separated authentication block, and then a parameter-by-parameter breakdown. Every section adds necessary value for a tool with no annotations, though the auth section is lengthy and some formatting breaks could be tightened.

  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 complexity (23 parameters, no output schema, no annotations), the description is remarkably complete. It covers auth, parameter semantics, special validation rules, sandbox restrictions, cross-references to register_agent for shared fields, and the return value. It leaves little ambiguity for an agent attempting 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 description coverage is 0%, so the description must compensate. It adds meaningful semantics for many parameters (e.g., agent_id immutability, contact_email's role, capabilities format, payload_schema allowed keys, message_protocol implications, and the payment_* rule). However, some parameters like org_name, protocol, specialty, and settlement_rail are left to inference from their names, so it does not fully cover all 23.

  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: 'Update an existing agent's profile fields' with specific behavior ('Only provided fields are changed; omitted fields remain unchanged'). This distinguishes it from sibling tools like register_agent and get_agent, and clearly identifies the resource being acted upon.

  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 for when to use the tool (updating existing agents) and emphasizes partial-update semantics. However, it does not explicitly name alternatives (e.g., 'use register_agent for new agents') or state exclusions, so it stops short of a 5.

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

• promote_sandbox_agentA
  4.8/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 and excels: it details auth header requirements (X-API-KEY or AIDRESS_API_KEY), enumerates exactly which fields are copied and which are never moved, and notes that every promotion is logged. This is rich behavioral disclosure covering side effects, constraints, and auditing.

  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 well-organized into paragraphs covering action/auth, pairing requirement, field movement lists, logging, and a recommendation. Every sentence contributes useful information without redundancy, and the first sentence immediately states the core 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?

  For a two-parameter tool with no annotations and no output schema, the description is exceptionally complete. It covers purpose, prerequisites, side effects (including what is preserved), auth requirements, logging, a recommended prior step, and the return payload. No critical context is missing.

  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 input schema has zero descriptions and simple string IDs, so the description must add meaning. It explains that sandbox_agent_id is the source and real_agent_id is the target, and that they must be a confirmed pair. It also lists the fields that will be copied, giving functional context to what the parameters influence.

  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 action: 'Push a sandbox agent's tested config onto its paired live agent,' clearly identifying the verb and resource. It distinguishes the tool from siblings by framing it as the promotion step in a sandbox-to-live workflow, and later references preview_sandbox_match as a prior step, further clarifying its unique 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 a prerequisite (confirmed pairing via register_agent clone_from_agent_id) and warns that unrelated pairs are rejected with 403. It recommends calling preview_sandbox_match first, giving a clear alternative/lead-in. However, it does not explicitly contrast with other config-editing tools like update_agent, so it falls short of complete when/when-not guidance.

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

• protocol_referenceA
  4.8/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 states the tool 'looks up' and returns 'worked example' flows, which implies a read-only, non-destructive operation. It also details what each topic returns (e.g., 'two-step initialize -> tools/call flow'), providing useful context. However, it does not explicitly mention side effects or lack thereof, and omits return format/pagination, so it falls short of a perfect score.

  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 yet comprehensive, front-loading the key instruction in the first sentence. It uses a clear, scannable list for topics, and every sentence serves a purpose—either explaining when to call or what to expect. No redundancy or fluff, so it scores high for structure.

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

  Completeness5/5

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

  For a single-parameter reference tool, the description is complete: it covers all possible topics, when to use each, and what information they return. It also explains the design rationale (keeping other docstrings short), which helps the agent understand the tool's role. No output schema is provided, but the description sufficiently conveys the return value for each topic, so the context is fully adequate.

  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 input schema only lists an enum without descriptions, but the description explains each enum value in detail with trigger conditions and expected content. This goes far beyond the schema, turning bare values into actionable guidance (e.g., 'register_capability_confirmation' is for when register_agent returns HTTP 202). The description fully compensates for the 0% schema description coverage.

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

  Purpose5/5

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

  The description clearly states this tool 'looks up the worked example for an edge-case protocol flow, on demand', which is a specific verb and resource. It explicitly differentiates itself from sibling agent-management tools by focusing on protocol reference and on when to call it. The topic list further clarifies the exact scope, making the purpose unmistakable.

  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 gives explicit usage guidance: 'Call this the FIRST time you actually hit the situation — not proactively every session.' It also provides concrete scenarios for each topic (e.g., 'you're about to call_agent a target whose message_protocol is "mcp"'), which helps the agent decide when to invoke it versus relying on other tools.

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

• verify_agentA
  4.8/5.0
  Behavior5/5

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

  With no annotations provided, the description fully carries the behavioral disclosure burden. It details return contents (trust_score, verified, capabilities, flags, routing, payload_schema), the 404 error semantics and how to interpret it as 'do not transact', and provides trust tier thresholds with concrete action implications. This is far beyond basic operation disclosure.

  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-organized and front-loaded with the core purpose, then flows into usage guidance, return details, trust tiers, and a final instruction. Though it is longer than strictly necessary, every sentence serves a distinct functional purpose—covering when, what, and how. The structure aids scanning, but a bit more terseness would push it to 5.

  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 having only one parameter and no output schema, the description provides complete context for an agent to use the tool effectively. It explains return fields, error handling, trust thresholds, and the imperative to check payload_schema before calling agents. There are no significant gaps in behavioral or contextual information needed for selection and 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?

  The schema only defines agent_id as a required string with no description (0% coverage), so the description must compensate. It does so by explaining that agent_id is the lookup key, notes possible sources (user/counterpart vs match_agents/list_registry), and describes the 404 behavior when the id is not in the registry. It lacks explicit format/example, but the behavioral semantics are well covered.

  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: 'Look up an agent's trust profile by agent_id.' It clearly distinguishes itself from siblings by explicitly noting that match_agents/list_registry already return the same trust object, thereby positioning verify_agent as a dedicated lookup for trust profiles from alternative sources or fresh reads.

  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: NOT required after match_agents/list_registry, but appropriate when agent_id comes from elsewhere or a fresh read is needed before high-value actions. It names the alternative tools and clarifies the decision path, exceeding simple implied usage.

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

• call_agentA
  4.9/5.0
  Behavior5/5

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

  With no annotations provided, the description fully bears the transparency burden. It discloses that all calls are logged, requires review_transaction within 24h, describes error codes (401/403, 409, 422, 402), explains auth mechanisms (bearer token, env var, set_agent_key), and reveals that per-call key parameters are intentionally absent to avoid trace leakage. It also explains the 402 payment flow in detail. This is exemplary behavioral disclosure.

  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 long but justified given the tool's complexity (8 parameters, multiple protocols, auth, payment flow). It is front-loaded with the core purpose and then logically groups parameter details. Some sentences are dense and could be restructured (e.g., splitting the x_payment block), but nothing is redundant. It earns its length.

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

  Completeness5/5

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

  The description covers all necessary context for a high-complexity tool: return value (transaction_id and HTTP status), error conditions, auth setup, follow-up review requirement, and payment handling. Even without an output schema or annotations, an agent can fully understand invocation, side effects, and expected outcomes.

  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 description adds rich meaning to every parameter beyond the bare schema. For example, message_protocol gets an entire block explaining each enum value and its payload implications; mcp_session_id is scoped to mcp protocol; forwarded_headers describes verbatim relay and reserved-header exclusions; x_payment gets a detailed payment-flow explanation. Even though the schema has 0% coverage, the description fully compensates, making each parameter's semantics crystal 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 opens with a specific verb and resource: 'Send a request to a registered agent through the Aidress proxy.' This clearly distinguishes call_agent from siblings like verify_agent/match_agents (which provide agent metadata) and review_transaction (which handles post-call review). The scope is explicit and unambiguous.

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

  Usage Guidelines5/5

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

  The description gives extensive when-to-use guidance: it explains how to obtain message_protocol from verify_agent/match_agents, when to use protocol_reference for MCP handshakes, when to call review_transaction (with a skip condition), and when to set x_payment. It also states that anonymous calls are not allowed, clarifying a key limitation. This far exceeds basic usage guidance.

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

• review_transactionA
  4.9/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 transparency burden. It thoroughly discloses the action's effects: it modifies trust ratings, enforces anti-gaming rules, and returns the updated trust object. It also explains rejection conditions and auth requirements, leaving no significant behavioral ambiguity.

  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 longer than average, but every section adds value: purpose, parameter semantics, auth options, and anti-gaming constraints. It is well-structured with clear separations, but the auth section is slightly verbose and could be tightened without losing essential guidance.

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

  Completeness5/5

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

  The tool has moderate complexity with four required parameters, no output schema, and no annotations. The description fully covers all necessary context: what triggers a valid review, auth methods, constraints, and the return value. It leaves no major questions unanswered for an agent deciding whether and how to invoke it.

  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 description coverage is 0%, so the description must compensate, and it does. It explains each parameter: caller_agent_id (who submits), receiver_agent_id (who is reviewed), success (boolean for completion), and score (1-10 trust rating). It also clarifies that no transaction_id parameter is needed, which prevents incorrect parameter usage.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: 'Submit a trust review after a confirmed exchange with another agent.' It clearly distinguishes this from sibling tools by noting that no transaction_id is needed and that reviews without a real prior /call exchange are rejected, which highlights its unique role in the trust review process.

  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 states when to use the tool ('after a confirmed exchange') and lists prerequisites (caller trust_score >= 50, not self-review, not same org domain, one review per exchange). It also provides actionable auth setup instructions for both remote and local use, giving clear context for invoking the tool correctly.

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

• claim_bearer_keyA
  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: it returns a 400 error for invalid/used tokens, does not auto-store the key, and is the only place a key is currently minted. These details go beyond the schema and help the agent predict side effects.

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

  Conciseness5/5

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

  Though the description is a few sentences, each sentence earns its place: purpose, parameter clarification, and important caveats. The structure with a separate token explanation improves readability without unnecessary padding.

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

  Completeness5/5

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

  The tool is simple (one parameter, no output schema), and the description covers what is returned, error cases, and the recommended follow-up action. It also provides context about being the only key-minting step, making it complete for an agent to invoke successfully.

  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 0%, but the description thoroughly explains the sole parameter (token), including acceptable formats (full URL or the part after 'token=') and that the query string is parsed out. This fully compensates for the minimal 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 redeems a claim-token link's token and returns the actual bearer key. It references the specific source fields (register_agent/rotate_agent_key claim_link) and identifies it as the GET /rotate?token= step, distinguishing it from sibling tool 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?

  It explicitly states when to use the tool (after register_agent or rotate_agent_key provides a claim_link) and provides a clear 'when-not' by noting the key is not auto-stored, directing users to call set_agent_key afterward for subsequent authentication. This gives actionable guidance and names the alternative tool.

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

• import_agentA
  5/5.0
  Behavior5/5

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

  With no annotations, description fully discloses behavior: read-only operation (nothing written to DB), fetches /.well-known/agent-card.json, returns preview and missing fields. No hidden side effects.

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

  Conciseness5/5

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

  Description is concise: 4 sentences with a bullet list for return fields. Front-loaded with action verb 'Pre-populate'. Every sentence adds value without 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?

  Despite no output schema, description details return fields (source_url, preview, missing_fields, note). Given low complexity (one param) and clear purpose, description is complete for agent to use correctly.

  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 one parameter 'domain_url' with 0% description coverage. Description adds meaning by explaining it's the domain to fetch from, giving examples ('https://example.com' or 'example.com'). Fully compensates for missing 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 clearly states the tool's purpose: pre-populate an Aidress registration from a domain's A2A agent card. It specifies the action (fetch and map) and the resource (agent card from well-known URL), distinguishing it from sibling register_agent.

  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: to preview before calling register_agent. Tells the agent that nothing is written to DB and to review preview, fill missing fields, then call register_agent. Provides clear alternative.

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

• list_registryA
  5/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 and pays it off: it clearly discloses the lack of trust/verified gating, warns that results may include unverified agents, and states that trust_score/verified/flags are already included in results. This gives the agent crucial behavioral context for a registry listing tool.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose and then adds meaningful usage guidance and parameter details. Every sentence earns its place—there is no fluff or repetition, and the structure is easy to scan.

  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 having no output schema, the description tells the agent what to expect in results (trust_score/verified/flags) and covers pagination behavior. The tool is simple (2 optional params), and the description fully equips an agent to select and invoke it correctly.

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

  Parameters5/5

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

  Although the schema has no descriptions, this description fully documents both parameters: limit has max 200 and default 50, offset skips agents for pagination with default 0. This goes well beyond the bare schema and fully compensates for the 0% 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 browses all agents in the Aidress registry with pagination. It distinguishes itself from siblings by explicitly contrasting with match_agents for capability-filtered discovery and by explaining that verify_agent is unnecessary for results.

  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 when to use this tool (browsing the full registry or building an index) and when not to (use match_agents for capability-filtered discovery). It also tells the agent that verify_agent is not needed on list results, which prevents unnecessary calls.

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

• match_agentsA
  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 key behaviors: no trust/verified gate, results may include unverified agents, ranking varies based on capability inclusion, and each result contains a full trust object. This goes well beyond simple operation scope, addressing potential misconceptions and guiding agent decisions.

  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 moderately long but every sentence earns its place. It is front-loaded with purpose, then alternates between behavioral caveats and parameter details, with a clear structured flow. No redundancy wastes the reader's attention.

  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 has no output schema, no annotations, and 4 optional parameters, the description is exceptionally complete. It explains the return format (ranked trust objects with payload_schema), ranking behavior, and error-avoidance guidance (check payload_schema before sending). An agent can confidently select and invoke this tool based solely on the description.

  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 0%, but the description compensates thoroughly: it explains each parameter's meaning, gives examples for capabilities, lists enums for settlement_rail and message_protocol, and notes org_name is exact case-insensitive. The requirement that at least one filter must be passed is also stated, which the schema does not convey.

  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 finds agents matching combinations of capability, settlement rail, org, or message protocol, ranked by composite score. This specific verb-resource-scope structure distinguishes it from siblings like list_org_agents and verify_agent.

  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 is given: at least one filter must be provided, all filters are optional, and results include trust data so verify_agent is unnecessary for listed results. It also specifies when to use verify_agent instead (for unknown agent IDs or fresh checks), providing clear alternative selection.

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

• preview_sandbox_matchA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description fully discloses behavioral traits: auth requirements (X-API-KEY header, AIDRESS_API_KEY), error condition (403 if no live counterpart), comparison logic (draft's own config but live stats), competitor filtering (verified=true, trust_score>=50, live counterpart excluded), and side-effect-free execution. It even notes the explanation is null if LLM call fails and never blocks results.

  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 structured in clear paragraphs: purpose, auth, parameter details, behavioral details, return values. Every sentence adds necessary context; there is no fluff, despite the length.

  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 complex preview tool with no output schema, the description covers inputs, outputs (ranked results, draft_agent_id, explanation or null, disclaimer), error conditions, and side effects. It is complete enough for an agent to invoke correctly.

  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 no descriptions (0% coverage), but the description explains all three parameters: sandbox_agent_id (prerequisite/403), required_capabilities (same semantics as match_agents), and settlement_rail (enum values and omission behavior). This fully compensates for the empty 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 opens with 'Preview exactly where a sandbox agent's tested config would rank against REAL, live competition — before you actually promote it,' providing a specific verb (preview), resource (sandbox agent config vs live competition), and purpose (pre-promotion evaluation). It distinguishes itself from sibling tools like promote_sandbox_agent and match_agents by framing the comparison and non-mutating nature.

  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 states the context 'before you actually promote it' and defines prerequisites (sandbox_api_key, sandbox_agent_id must have live counterpart). It references register_agent's clone_from_agent_id and match_agents semantics, and clarifies 'Nothing here is written anywhere', telling the agent when this preview tool is appropriate vs actual promotion.

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

• set_agent_keyA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description fully discloses behavioral traits: key held in memory only, does not survive restart, not validated immediately (first auth call confirms), no-op if env var is set, and shared slot on remote connector. This goes far beyond the bare schema and gives the agent critical operational 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?

  While longer than typical descriptions, every paragraph earns its place: purpose, usage timing, security rationale, env var precedence, remote-connector caveat, and parameter clarification. The structure is logical with clear section transitions, and there is no redundant repetition of schema data or annotations.

  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 security-sensitive nature and the complex interactions with environment variables, session lifetime, and remote vs local deployment, the description is exceptionally complete. It covers all necessary operational contexts, and since there is no output schema, it appropriately focuses on setup and caveats rather than return values.

  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 input schema only shows 'agent_key' with no description (0% coverage). The description compensates fully by specifying the format ('aidress-agent-sk-...') and provenance ('returned by register_agent'), and distinguishes agent keys from org keys which cannot be set in-session.

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

  Purpose5/5

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

  The description states a specific verb+resource+scope: 'Store a bearer agent key for the duration of this MCP session.' It clearly distinguishes itself from sibling tools like register_agent (which creates the key) and rotate_agent_key (which changes it), and explains its role in enabling authentication for other tools.

  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 immediately after register_agent returns an agent_key.' It also gives exclusions and alternatives: explains why not to pass keys per-call (security rationale), warns against use on the hosted remote connector (with specific alternative: send Authorization header), and clarifies env var precedence (AIDRESS_AGENT_KEY wins).

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