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 the return shape (events array), ordering semantics ('last limit matches in log order, oldest first within that slice'), edge-case behavior (missing log returns empty array, malformed JSON lines skipped), read-only nature, and two important caveats (redaction with summary/hash metadata, not an immutable audit service). That 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?

Front-loads purpose, then return semantics, then edge cases, then caveats, then a minimal example. Every sentence adds information an agent would otherwise have to guess; nothing is repeated from the schema verbatim.

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?

Two optional parameters, no output schema, no annotations — and the description still covers purpose, filtering, ordering, paging behavior, error tolerance, and data-fidelity caveats. An agent can call this correctly and interpret the result without further information.

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 100%, so the baseline is 3; the description earns above that by clarifying that limit selects the last N matches and that ordering is oldest-first within the returned slice, which the schema does not state. It also confirms resource is an optional substring filter over serialized details, reinforcing the schema's caveat that it is not exact structured matching.

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 ('Inspect') and resource ('recent local Mesh history') and enumerates the record types covered (messages, registrations, approvals, policy denials). It also explicitly scopes out what it does NOT return ('non-Mesh HTTP/secret audit events'), which separates it from siblings like check_messages, secret.status, and http.request.

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?

Frames the use case clearly as 'troubleshooting' and lists the event categories it covers, plus an explicit exclusion of non-Mesh HTTP/secret events. It stops short of naming an alternative tool to use for those other cases, so the agent must infer the routing from sibling names.

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 load and does well: it names the exact return fields, declares the operation is non-mutating ('Does not mark messages read'), and clarifies a subtle scoping rule that pending approvals include those assigned to the agent or its registered team, not merely requests it created. It stops short of failure modes or cost/latency characteristics, which keeps it from 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?

Four short sentences, front-loaded with the purpose, followed by return shape, scoping caveat, side-effect disclaimer, alternatives, and an example. Every sentence contributes a distinct fact with no restatement of the tool name.

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?

There is no output schema, so the description must describe return values — and it enumerates them precisely. For a single-parameter read tool, an agent has everything needed to decide and invoke 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 100%, so the baseline is 3, but the description adds a concrete invocation example ({"agent_id": "backend-agent"}) and reinforces that this is a caller-supplied local label rather than a credential. That extra framing helps an agent pick the value to pass.

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?

Specific verb (check) plus resource (local inbox counts) with an explicit statement of what is and isn't returned: agent_id, unread_count, pending_approval_count, and a notice, 'not message content'. It also carves itself apart from agentsecure.list_messages and agentsecure.read_message by name, so no schema opening is needed to disambiguate.

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?

States the triggering condition ('before answering whether this agent has messages or approvals') and routes to the two alternatives with their distinct purposes: list_messages for records, read_message to acknowledge one. Nothing about tool selection is left 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, the description carries the full burden and does so: read-only semantics, the exact status vocabulary, that reason text is redacted to summary/hash, that unknown IDs error out, and critically that an approved record neither executes an action nor lifts policy restrictions. That last point preempts the most likely agent misinterpretation of an 'approved' status.

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 read-only scope and return shape are front-loaded, and all six sentences carry distinct information (return fields, redaction, errors, non-granting semantics, alternatives). It is slightly dense for a one-parameter read tool, but no sentence is filler.

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?

There is no output schema or annotations, so the description must explain return values and side-effect profile — it does both, including the enumerated status values and the caution that approval does not trigger execution. Nothing an agent needs in order to call this 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 100% and the single approval_id parameter is fully documented in the schema, so the baseline is 3. The description only reinforces the constraint by noting that unknown IDs cause an error; it adds no format or syntax details beyond the schema's 'apr_...' guidance.

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 uses a specific verb and resource ('Read a previously created local approval without changing it') and immediately enumerates the returned fields (status, action/resource, required_approver, decision details). It explicitly separates itself from agentsecure.request_approval and agentsecure.get_policy_hint, so an agent can choose without opening any sibling 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 names the alternatives and the condition that selects them: request_approval to create a request, get_policy_hint to inspect policy. It also states clear exclusions ('neither requests nor grants approval') so an agent cannot mistake this for a mutation or a policy-evaluation 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?

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses non-execution, local-policy scope, which policy checks are performed, the returned fields, and the important limitation that this is not an authorization token or a guarantee about external permissions.

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 critical non-execution scope are front-loaded, followed by checked conditions, return values, limitations, alternatives, and an example. The paragraph is dense but free of filler and appropriately sized for a policy-evaluation 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?

Given no output schema and no annotations, the description supplies the missing context: it enumerates returned fields, states what is checked, and clarifies that existing approvals and external permissions are not covered. It is complete enough for an agent to invoke the 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 already 100%, so the schema documents parameter meanings in detail. The description still adds value with a concrete example and by tying target to the send_message check and noting that action/resource text is examined for sensitive markers.

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 and resource: evaluating a proposed Mesh action against the current local agent policy without executing it. It clearly distinguishes the tool from approval recording and network/secret policy inspection by naming those alternatives.

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 frames the tool as guidance rather than authorization, notes that approval records are not consulted, and tells the agent to use agentsecure.request_approval for review requests or agentsecure.policy.describe for HTTP network/secret configuration. This gives clear alternatives and when-not-to-use guidance.

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

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

With zero annotations the description fully carries the behavioral burden: destination-policy check ordering, vault-alias host restrictions, no redirect following, temporary grant revocation, secret sanitization of response bodies and headers, and the crucial semantic that HTTP error statuses are still returned as responses while config errors may surface as MCP errors. That is exactly the disclosure a mutation-capable network tool needs.

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 blocking rule, and every clause carries distinct information (policy check, redirects, revocation, return shape, error semantics). It is a dense run-on paragraph that could be split for scanability, but little is genuinely wasteful for a 9-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 exists, yet the description enumerates both success (blocked=false, status, reason, headers, UTF-8 body) and blocked (blocked=true, reason, rule_id, allow_command) return shapes plus sanitization behavior. Combined with 100% schema coverage and a worked example, an agent has everything needed to call it and interpret results.

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 100%, so the baseline is 3; the description goes beyond it by demonstrating placeholder placement in headers with a concrete example and stating the approval requirement for both host and secret name. It adds interpretation (the operation is authorized only if host and secret are approved) rather than merely restating field types.

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+resource (send one HTTP(S) request) plus the defining constraint that distinguishes it from any other HTTP tool: it requires ${ENV_NAME} secret placeholders. The final clause explicitly disclaims being a sandbox for other network tools, so an agent can immediately tell this apart from ordinary fetch tools and the agentsecure.* siblings.

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 an explicit when-not rule ("calls without placeholders are blocked (use ordinary network tools for those)") and prerequisites (host and secret must be configured and approved). It does not route to a named sibling such as request_approval when a call comes back blocked, though the mention of allow_command hints at that path without stating it.

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 and does so well: it discloses that lookup returns exists=false for unknown IDs, that the agents array is sorted by ID, that registration overwrites rather than merges, that an audit event is written, and that labels/scopes are not security boundaries. These are exactly the mutation and side-effect facts an agent needs.

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 the default behavior, then the mutation mode, then a caveat, then an example. Every sentence carries distinct information and nothing is repeated from the schema verbatim.

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?

A 9-parameter tool with no annotations and no output schema, yet the description covers both return shapes (exists + metadata, agents array, saved identity), overwrite semantics, and the non-security nature of the stored metadata. 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 100%, so the baseline is 3, but the description adds conditional semantics beyond the field docs: omitting agent_id lists identities, non-empty agent_id is required for register, and defaults are applied to omitted fields on overwrite. The worked example reinforces the minimal lookup call.

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 pair and resource: 'Look up or register identities in the local Community Mesh store.' It also distinguishes the two operational modes by argument shape, so an agent can tell what the tool does without opening 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?

It explicitly states when each mode applies: default lookup when agent_id is supplied, listing when agent_id is omitted, and write when register=true with a non-empty agent_id. There are no sibling tools with overlapping identity duties, so no explicit alternates are needed, but it also doesn't mention prerequisites or error handling.

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: it discloses ordering (newest first), empty-result behavior, the redaction model (body [redacted], body_summary capped at 120 chars, body_sha256 is a non-recoverable digest), and the non-mutating guarantee. It omits any statement about result-count limits or pagination for large mailboxes, which is the remaining behavioral gap.

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 return shape, then usage alternatives — a sensible order with no filler sentences. It runs slightly long, spending several clauses on redaction mechanics that could be compressed, but every sentence carries information.

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, so the description correctly spends its budget describing the returned fields (message_id, participants, subject, status, thread IDs, timestamps) and the redaction constraints an agent must respect. Combined with a 2-param schema at full coverage, nothing needed to call this 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 100%, so agent_id and include_read semantics (default false, unread only, neither setting marks read) are already fully documented in the schema. The description only adds a concrete example object, which is marginal value over structured fields — baseline 3 applies.

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?

Specific verb+resource ('List messages addressed to one agent in the local Community Mesh store') with explicit scope and return shape. It names the two sibling tools it is not (check_messages, read_message) and what each does instead, so an agent can pick without opening schemas.

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 routing: 'Use agentsecure.check_messages for counts only or agentsecure.read_message to mark a specific record read', plus the exclusion 'Does not mark messages read'. The when/when-not/alternative triple is fully covered, and an inline example call is provided.

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 exist, so the description carries the full burden and does most of it: it declares the operation is read-only ('Does not change policy'), enumerates what is returned (network domains/ports, IP restrictions, secret_aliases, project_bindings, usage instructions), explicitly excludes secret values, and warns it does not verify credentials. The only gap is that it never mentions auth/permission requirements for reading policy.

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?

Four tight sentences, front-loaded with the purpose and scope, then the return payload, then the negative behaviors, then the sibling routing. Every clause carries unique information; no filler.

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?

There is no output schema, so the description must describe the return shape, and it does so concretely (network allowlist, secret_aliases, project_bindings, usage instructions). Combined with the read-only caveat and exclusion of secret values, an agent has everything needed to call and interpret 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?

Zero parameters, so the baseline is 4; the description reinforces this with 'Takes no arguments', confirming no scoping inputs are needed. There is no additional semantics to convey beyond that.

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?

Specific verb + resource + scope: 'Inspect the current project's network rules and configured secret metadata'. It also fixes the moment of relevance ('before a secret-bearing HTTP request'), which separates it from siblings like agentsecure.http.request or agentsecure.identity at a glance.

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 ('before a secret-bearing HTTP request') and names two alternative tools with the exact condition that selects each ('secret.status for one env name', 'get_policy_hint for a Mesh action rather than HTTP destination policy'). Nothing is left 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, the description carries the full burden and does so well: it discloses the recipient-match requirement, error conditions, local state plus audit update on first read, idempotent re-reads, redacted body behavior, and the critical caveat that the recipient check compares caller-supplied IDs rather than authenticated identities.

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 dense and front-loaded: purpose first, then prerequisites, then return/idempotency semantics, then redaction caveat, then the alternative tool. Every sentence adds distinct information.

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 mutation tool with no annotations and no output schema, the description covers everything an agent needs: usage context, error behavior, return shape (status/read_at), idempotency, redaction constraints, and the audit implication.

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 100%, so the baseline would be 3. The description adds value beyond the schema by stating that agent_id must match the record's recipient and by reinforcing that the check is against caller-supplied labels, not authenticated identities.

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 ('Retrieve and acknowledge one local Mesh message') plus the scope ('after listing the inbox') and the side effect (acknowledgement). This clearly distinguishes it from the read-only sibling list_messages.

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 tells the agent to use agentsecure.list_messages to inspect without marking read, and describes the prerequisite of listing the inbox. The alternative and the condition that selects it are both stated.

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 operation order (mark read, then policy check, then create reply), thread/resource preservation, reply_to setting, both success and policy-denial return shapes, and the subtle side effect that the original can remain read even when sending is blocked. It also warns that bodies are redacted to a summary/hash rather than full-text delivery, which is exactly the kind of non-obvious behavior an agent must know before calling.

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 the core action and has no throwaway sentences, but the single dense paragraph packs many distinct clauses (ordering, returns, errors, redaction, alternative) and would be slightly easier to parse if broken up. Every clause still earns its place.

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 three-parameter mutation with no annotations and no output schema, the description covers prerequisites, side effects, success and denial return shapes, error cases, and redaction behavior. Nothing essential for a correct invocation 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 100%, so the baseline is 3, but the description adds relational meaning between parameters: message_id must be an existing message addressed to from_agent, and the reply is addressed to that message's original sender. That linkage goes beyond the individual field descriptions and clarifies the mismatch-error path.

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 ('Reply to a local Mesh message') and immediately scopes it to messages addressed to from_agent. It also distinguishes itself from the sibling agentsecure.send_message for new threads, so an agent can select correctly without opening 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?

Explicitly routes new threads to agentsecure.send_message and reserves this tool for existing messages addressed to from_agent. It also states the failure conditions (unknown message or recipient mismatch) that rule this tool out.

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 local state and audit writes, redaction of reason into a summary/hash, that repeated calls create separate requests, and that an approved record does not unblock policy. It stops short of stating permissions or concurrency/idempotency guarantees for the audit write, which keeps it from 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 scoping negatives, and dense with no filler sentences. It is a long single paragraph for a 5-parameter mutation, though each clause carries distinct information; light structure (bullets or a short return-value sentence) would improve scanability.

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 returned fields (approval_id, status, timestamps, etc.), describes side effects, redaction, and the downstream decision workflow. Nothing needed to invoke or interpret the call 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 100%, so the baseline is 3; the description goes further by supplying a concrete example call and tying the action label to the one supplied to get_policy_hint, plus noting requested_by should come from AGENTSECURE_AGENT_ID and is a caller-supplied label, not a credential.

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?

Opens with a specific verb and resource: 'Create a local pending approval record when a Mesh policy hint requires human review.' It also names the return object shape and distinguishes itself from siblings by stating it does not execute, notify, or change policy, and routes to get_approval_status.

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 an explicit trigger (a policy hint requiring human review), explicit non-capabilities (no messaging, no notification, no execution, no policy change), the follow-up tool to use (agentsecure.get_approval_status with the returned ID), and the exclusion that decisions happen outside these MCP tools. It even warns that approval does not auto-unblock policy.

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 and explains the return shape, including exists, env_name, and conditional source/provider/mode metadata. It also states that no secret value is returned, though it does not explicitly discuss read-only safety, permissions, or rate limits.

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

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

The description is front-loaded with the core purpose and then efficiently covers return values, exclusions, the relevant alternative tool, and a concise example. Every sentence contributes useful selection or invocation 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?

Given the low-complexity, one-parameter lookup and the absence of an output schema or annotations, the description supplies enough context to select and invoke the tool correctly. It covers purpose, return fields, exclusions, and the sibling alternative without requiring further inference.

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 already fully documents the single env_name parameter, including that it must be exact, without ${...}, and not an alias ID or secret value. The description reinforces this with an example but adds little semantic information beyond the 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 states a specific verb and resource: checking whether an environment name is assigned in the current project's secret configuration before using its placeholder. It clearly distinguishes this from a vault-value or credential-validity check and names the sibling tool for listing all aliases and bindings.

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 gives explicit usage context: use this before referencing a ${ENV_NAME} placeholder, and use agentsecure.policy.describe when you need to list all configured aliases and bindings. It also clarifies what the tool is not for, namely vault-value lookup or credential-validity checking.

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 well: it discloses both response branches (blocked=false with message/message_id/thread_id, blocked=true with reason and allowed_next_step), the redaction/audit behavior (redacted body, digest, heuristic summary retained), and the security warning about secrets. It stops short of covering failure modes such as unknown recipient IDs or policy-denial specifics, which keeps it at 4 rather than 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?

Behavior (what is stored) and the safety warning are front-loaded before the sibling pointer and example, which is the right ordering. It is dense but readable; the secrets warning and redaction detail are stated twice (description and body/from_agent schema), a minor redundancy in an otherwise tight definition.

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?

There is no output schema, and the description compensates by describing the exact return shape for both success and blocked outcomes. With a nested 'resource' object and six parameters, it covers the operational picture an agent needs: policy gating, non-delivery semantics, and irreversibility of the stored body.

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 100%, so baseline is 3. The description still adds value by supplying a concrete worked example ({"from_agent": "frontend-agent", "to": "backend-agent", "body": ...}) and by reinforcing the secrets constraint on body that the schema also flags. It does not, however, explain the 'type' enum's effect on policy/approval beyond what the schema lists.

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?

Opens with a specific verb+resource+scope: 'Create a new unread message in the local Community Mesh store for another agent.' It immediately separates itself from the closest sibling by naming agentsecure.reply_message as the in-thread alternative, so an agent can route 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?

Explicitly names the alternative (reply_message) and the condition selecting it, and gives concrete exclusions: does not launch/wake the recipient, contact a remote service, or prove read. It also states the policy/approval check that runs before a send, which is the key precondition an agent needs.

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