Aidress

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the full burden and does well: it discloses the absence of any trust/verified gate, the single-capability OR semantics, the ranking fallback when capabilities is omitted, the contents of the trust object and payload_schema, and the 402/payment flow. It omits pagination, result limits, and any auth requirements, which keeps it short of a 5.

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

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

Front-loaded with purpose and the key gate caveat, then organized by filter, then returns, then the payment flow. Slightly long — the extended 402/signing paragraph is adjacent to the tool's core job and could be trimmed, but every block is substantive.

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

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

For a 4-param, 0%-coverage, no-annotation, no-output-schema tool, the description covers everything needed: all filters, the at-least-one rule, return shape (trust objects, payload_schema fields), the sibling relationship, and the downstream payment path. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it explains the capability-list format with examples, the settlement_rail enum values plus the ANY-of list semantics, exact case-insensitive matching for org_name, and the message_protocol values. It adds semantics the schema cannot express (ANY matching, omission behavior), though example values for message_protocol endpoints are thin.

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

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

States a specific verb and resource ('Find agents') plus the exact filter dimensions and ranking basis ('composite score: capability match + trust + success rate'). It also explicitly distinguishes itself from sibling verify_agent, so an agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use-the-alternative guidance: 'Use verify_agent only for an agent_id you don't have match/registry data for, or to force a fresh check before a high-value action.' It also states the at-least-one-filter constraint and that results can include unverified agents, so the agent knows when NOT to rely on this tool alone.

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

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

With no annotations, the description carries the full burden and does so: it discloses auth requirements (sandbox_api_key, X-API-KEY header remotely, AIDRESS_API_KEY locally), the 403 failure mode, that nothing is written ('the draft's ranking entry exists only for the duration of this call'), which fields come from the live counterpart vs the draft, competitor filtering rules, and that a null explanation is non-blocking. This is unusually complete 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.

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

Long but organized: the purpose leads, then a parameter block, then the comparison semantics, then return values. Near every sentence carries distinct operational information, though the density is high and a little could be trimmed. Front-loading is good.

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

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

No output schema exists, and the description steps in by describing the return payload (ranked list with draft at its earned position, draft_agent_id, nullable explanation, disclaimer) as well as auth and error behavior. An agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 0%, so the description must compensate fully, and it does: sandbox_agent_id's live-counterpart requirement and 403 behavior, required_capabilities' matching semantics via match_agents, and settlement_rail's optional filter values ('x402', 'stripe', 'manual', or a list, or omit for any). Every parameter gains meaning beyond the bare schema.

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

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

States a specific verb and resource ('preview where a sandbox agent's tested config would rank') and frames it against promotion, which cleanly separates it from match_agents (live matching) and promote_sandbox_agent (the actual promotion). An agent can identify the exact operation without opening any schema.

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

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

Explicitly positions usage 'before you actually promote it' and points to register_agent's clone_from_agent_id and match_agents for related semantics, giving clear preconditions (sandbox agent must have a confirmed live counterpart). It does not spell out an explicit when-not-to-use case, but the surrounding routing is unambiguous.

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

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the burden and does well: for every topic it discloses what the response contains (two-step initialize -> tools/call flow, RFC 9421 header format, error meanings). It never explicitly states the call is side-effect-free or whether results are cached, which keeps it just short of full behavioral coverage.

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

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

The description is long, but front-loaded with purpose and usage cadence before the per-topic catalogue, and every bullet pairs a trigger with a return summary, so little is wasted. The dense enumerated layout is justified by the six mutually exclusive topics.

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

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

No output schema, no annotations, one enum parameter — the description supplies everything needed: when to call, which topic selects which scenario, and what each topic returns. Nothing required to invoke it correctly is missing.

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

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

Schema description coverage is 0% and the enum values carry no inline descriptions, so the description must compensate — and it does fully, mapping each of the six topics to both its triggering situation and the content returned. No enum value is left unexplained.

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

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

States a specific verb and resource ('Look up the worked example for an edge-case protocol flow, on demand') and clarifies its architectural role — it exists so other tools' docstrings can stay short. This makes it immediately distinguishable from action siblings like register_agent and call_agent.

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

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

Explicit when-to-use and when-not: 'Call this the FIRST time you actually hit the situation — not proactively every session.' Each topic additionally names the precise trigger condition (e.g. 'register_agent just returned HTTP 202', 'you hit 401/403 on a signed request'), routing the agent unambiguously.

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

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

With no annotations, the description carries the full burden and does: it discloses that agent_key is never returned directly (you get a claim_link token), the 70-vs-40 trust_score outcome of an org key, the HTTP 400 rejection for invalid public_key, the 202 capability_confirmation_required flow, and background 402 quote reconciliation against price_schedule. These are non-obvious behaviors an agent cannot 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.

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

Despite its length, the description is tightly organized with required/optional sections, grouped bullets, and bolded headings, and the required field plus purpose are front-loaded. Every block (key delivery, common, less-common, error flow) earns its place for a 26-parameter tool.

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

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

No output schema or annotations exist, yet the description covers the needed context: key-delivery branching, verification status outcomes, the async confirmation flow, and error responses. Nothing essential for a correct first call appears to be missing.

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

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

Schema coverage is 0% across 26 params, so the description must compensate and largely does: it documents formats (base64url Ed25519, 32 raw bytes), constraints (one agent per org_domain, weight caps 3/2/1 with max 6 capabilities), defaults (http_methods POST, message_protocol a2a), and cross-field requirements (price_schedule needs payment_network/pay_to/asset in the same call). The remaining uncommon fields are deliberately pointed to protocol_reference.

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

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

The opening sentence states a specific verb (register) and resource (a new AI agent or human) with a clear target (the Aidress trust registry). It is distinct from siblings like update_agent, import_agent, and get_agent, so an agent can route without inspecting the schema.

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

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

Explicit when-tos are given: choose contact_email when someone can open a claim link, choose public_key when nobody can (fully autonomous agent), use org key to auto-verify at 70 vs 40. It also names the follow-up tools (claim_bearer_key, rotate_agent_key, protocol_reference) and the exact fork (HTTP 202 → register_capability_confirmation), leaving little to inference.

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

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the full burden and does so richly: it discloses the ordering of server-side auth checks, the immediate-return behavior on the signature path, a TEMPORARY server-side behavior change overriding normal output, rate limiting (429) on claim-link requests, and specific failure codes (403/400/404). This is unusually thorough 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.

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

The purpose and key-lifecycle constraint are front-loaded, and the auth-path list and error list are well separated with structure. It is long and slightly dense, with return-field behavior split across two places (the signature path paragraph and the TEMPORARY notice), but nearly every sentence is load-bearing for a security-sensitive operation.

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

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

For a complex, security-critical mutation with no output schema and no annotations, the description covers return fields (agent_key, status 'rotated', claim_link), the current override behavior, auth prerequisites, and error conditions. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 0% and there is only one parameter; the description defines agent_id as 'the agent whose bearer key to rotate', which adds modest meaning beyond the bare 'Agent Id' title. It gives no format, example, or lookup guidance, so it only partially compensates for the coverage gap.

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

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

The opening sentence states a specific verb and resource ('Request rotation of an agent's bearer key') and immediately clarifies the key lifecycle ('the previous key stops working the moment the new one is actually claimed'). It explicitly routes the reader to the sibling claim_bearer_key, so an agent can distinguish the two without opening either schema.

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

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

It clearly describes the conditions selecting each auth path and states that the signature route is 'the only self-service route for an agent with no human able to click a claim link', which is strong context. It does not, however, contrast against other key-manipulation siblings such as set_agent_key, so the when-not guidance is incomplete.

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

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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the full behavioral burden and does so richly: three auth mechanisms with concrete setup steps, public_key replacement semantics and 400-on-invalid behavior, payload_schema's four-key allowlist with 422 on unknown keys, the mutual requirement of all three payment_* fields, and the sandbox-only restriction. It even explains why key params are deliberately absent 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.

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

Front-loaded with purpose, then a well-organized auth block, then parameter notes; the formatting is scannable. The auth block is heavy and largely duplicated boilerplate relative to the tool's core behavior, which blunts conciseness, but for a 24-param mutation tool the overall length is defensible.

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

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

Given 24 parameters, no annotations, and no output schema, the description supplies the auth model, mutation semantics, and validation rules an agent needs, plus a one-line return statement ('Returns the updated trust object'). A few unmentioned params and no detail on the trust object's shape keep it short of fully complete.

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

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

Schema coverage is 0% across 24 params, so the description must compensate; it does so with high-value semantics for public_key (base64url, 32 bytes, replaces prior key, enables self-minted bearer keys), capabilities, payload_schema, message_protocol, auth_header_name and the payment_* group. It leaves several params (org_name, protocol, specialty, org_domain, contact_info, endpoint_url, http_methods, settlement_rail, accepted_terms_format) unaddressed, but the covered ones carry real meaning beyond their names.

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

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

States a specific verb and resource ('Update an existing agent's profile fields') and immediately adds the partial-update semantics ('Only provided fields are changed; omitted fields remain unchanged'), which distinguishes it from register_agent's create semantics. Reference to register_agent for field formats further anchors its role.

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

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

Usage is implied rather than stated: it explains partial-update behavior and gives three auth paths, but never explicitly says when to pick this over siblings like register_agent or promote_sandbox_agent, nor does it state preconditions beyond auth. The SANDBOX ONLY note on pull_from_agent_id is the one clear usage constraint.

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

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

With no annotations, the description carries the full burden and does so richly: return fields, a 404 semantic mapped to 'do not transact', trust-tier thresholds with recommended safeguards, staleness reasoning, and the x402 price-schedule/payment path. This is far beyond what annotations would normally supply.

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

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

Key routing information is front-loaded well, but the definition is bloated: the long x402/payment-signing passage is really call_agent guidance embedded in a lookup tool's description. That material is relevant context but dilutes the core purpose and could be trimmed or cross-referenced.

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

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

No output schema exists, yet the description enumerates the returned trust object (trust_score, verified, capabilities, flags, routing, payload_schema) and explains the payload_schema fields and the 404 outcome. An agent has everything needed to interpret the result and act on it.

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

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

Schema coverage is 0% and the sole required parameter agent_id has no description in the schema. The description gives useful semantic context for where the agent_id should come from (user/counterpart-supplied vs. a registry result), but adds nothing about its format or validity constraints, so it only partially compensates.

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

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

The first sentence gives a precise verb+resource ('Look up an agent's trust profile by agent_id'), and the second explicitly distinguishes it from siblings match_agents and list_registry, which already return the same trust object. An agent can pick this tool over its siblings without opening any schema.

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

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

It states exactly when NOT to use it ('NOT required after match_agents/list_registry'), when TO use it (agent_id obtained from elsewhere, or a fresh read before a high-value action on potentially stale data), and names the alternative. This is explicit routing guidance.

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