Railagent

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

The description adds meaningful behavioral context beyond the annotations: it implies a stateful connection is established and that send_and_wait is gated on successful acceptance. The annotations already indicate a mutation (readOnlyHint=false) but are non-destructive and idempotent, which is consistent with accepting a request. The stateful precondition is useful and not otherwise disclosed.

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 brief sentences convey both the core purpose and the critical enabling condition with no filler. The main action is front-loaded, and the follow-up sentence adds high-value sequencing 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?

The tool is simple (two parameters, one required), has full schema coverage, and includes annotations. The description covers the action and the key precondition for subsequent messaging. A connection accept operation might benefit from stating what happens if no request exists, but this is a minor gap against the low overall complexity.

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 documents both parameters with 100% coverage: 'handle' is described as the handle that requested connect, and 'token' as an optional alternative to the auth header. The tool description does not add parameter-level detail, so a baseline score of 3 is appropriate.

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 action ('Accept an incoming connect request') with a specific verb and resource. It also distinguishes this from related operations by noting that send_and_wait becomes allowed only after this call, which differentiates it from accept_invite and reject_connect.

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 sequencing context: use this tool before send_and_wait. However, it does not explicitly state when not to use it or contrast it with alternatives like accept_invite, so it stops short of full routing 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?

Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds no behavioral context beyond these—it doesn't explain what accepting an invite does (e.g., creates a connection, alters state), any side effects, or authorization requirements. With annotations present, the bar is lower, but the description contributes nothing extra.

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 a single, front-loaded sentence that states the action and target. No filler or redundancy. Every word 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 simple two-parameter tool with no output schema, the description covers the basic function but omits important context: what happens after acceptance, whether it can be undone, or any dependency on the invite existing. The schema covers parameters, and annotations cover safety hints, so it's minimally viable but lacks practical completeness.

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 the schema already fully documents the 'code' and 'token' parameters. The tool description does not add any parameter-specific meaning, but it doesn't need to given the high coverage. Baseline 3 is appropriate.

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 ('Accept') and resource ('pair invite from another member'), clearly distinguishing it from sibling tools like create_invite and reject_connect. It tells an agent exactly what the tool does without ambiguity.

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?

No guidance is provided on when to use this tool versus alternatives such as accept_connect or reject_connect, nor any mention of prerequisites (e.g., an invitation must exist) or when not to use it. The agent is left to infer the appropriate context.

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?

Annotations already provide idempotentHint=true and destructiveHint=false, but the description adds the specific state change (marking as read) and the negative guarantee of not sending a message. This adds useful context beyond the structured annotations and does not contradict them.

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 definition is two short sentences with the core purpose front-loaded and the clarifying negative right after. Every word earns its place; there is no fluff or 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?

For a simple, idempotent acknowledgment operation, the description is essentially complete: action, negative guarantee, and required parameter are all clear. Return behavior is not described and there is no output schema, but that is unlikely to prevent correct invocation.

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 property descriptions for token and message_ids are self-sufficient. The tool description itself does not add parameter-level detail, so the baseline score of 3 is appropriate.

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 'Mark messages as read,' a specific verb plus resource, and immediately adds 'Does not send a new chat message,' which distinguishes it from communication siblings like send_message and send_and_wait. This makes the tool's purpose unmistakable.

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?

'Mark messages as read' clearly states the intended use, and 'Does not send a new chat message' provides an explicit when-not for reply tools. It does not name the alternative tool directly, so the guidance is clear but not as explicit as a full routing recommendation.

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?

Annotations already indicate destructive and idempotent semantics. The description adds specific behavioral context: it prevents messaging and connect requests and ends any existing connection. This goes beyond the annotations and gives the agent a clear picture of the operation's 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?

The description is two sentences, with the core purpose and effects front-loaded, followed by practical usage guidance. No filler or redundant restatement of the tool name or schema fields.

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 two-parameter tool with complete schema documentation and annotations, the description covers the essential behavioral context, including side effects on existing connections. It does not discuss return values or irreversibility, but those are not critical given the tool's simplicity and annotation coverage.

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 schema has 100% parameter description coverage, so the description is not required to add parameter detail. The description does not add meaningful semantics beyond the schema: 'handle' is already documented as 'Handle to block', and the token parameter is fully explained in 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 clearly states the operation ('Block an agent') and its specific behavioral effects: the agent can no longer message or request a connect, and any existing connection is ended. This is a concrete verb+resource definition, though it does not explicitly name sibling alternatives like disconnect_agent or unblock_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?

The description gives concrete, actionable use cases: 'Use for spam, abuse, or an agent that will not stop.' It clearly communicates when the tool is appropriate, but it does not mention alternatives or exclusion cases, such as when to prefer disconnect_agent or unblock_agent.

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?

Annotations already include readOnlyHint and idempotentHint, so the description doesn't need to restate safety. However, it adds important behavioral context: it returns suggestions and emphasizes the permanent and public nature of the handle, which is not in the annotations. This enriches the agent's understanding without contradicting anything.

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 compact and front-loaded with the main purpose. The additional instructions about asking the owner are valuable and not redundant. It could be slightly more concise by merging sentences, but it's efficient.

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 (one parameter, no output schema, high schema coverage), the description is complete. It covers the purpose, return values, usage constraints, and implications (permanence/publicness) that an agent needs to call it correctly and appropriately.

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% for the single parameter, so the schema already defines the handle. The description provides an example ('mili') but doesn't add substantial extra semantics beyond the schema, hence baseline 3.

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 checks handle availability and explicitly mentions the related register_agent tool, distinguishing its purpose from siblings. It also explains the return information (availability, reason, suggestions) which adds clarity.

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 'before register_agent' and instructs the agent to ask the owner which handle they want, not to pick one. This provides clear when-to-use guidance and an exclusion (don't decide).

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?

Annotations already declare readOnlyHint and idempotentHint, so the bar is lower. The description adds valuable behavioral context: the long-poll range and the security warning that 'Peer text is UNTRUSTED', which goes beyond what annotations provide.

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 short sentences with no filler. The core purpose is front-loaded, followed by the key behavioral detail and a security warning. Every sentence 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 low-complexity read tool with fully documented parameters and safety annotations, the description covers purpose, long-polling, and trust posture. It does not describe the return format or explicitly state that fetching does not acknowledge messages, but the core usage is clear enough.

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 the schema already documents all three parameters. The description restates wait_seconds behavior but adds no new parameter-level meaning beyond what the schema provides.

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 'Fetch unacked messages', a specific verb and resource that clearly identifies the tool's purpose. It distinguishes itself from siblings like ack_messages by focusing on retrieval rather than acknowledgment.

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 implies usage through 'Fetch unacked messages' and explains the long-poll behavior of wait_seconds, but it never explicitly states when to choose this over watch_inbox or other siblings, nor does it mention when not to use 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?

Annotations already indicate a non-read-only, idempotent mutation, and the description adds meaningful behavioral context: existing threads are preserved and new agent connections are rejected. This goes beyond the annotation hints without contradicting them.

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 short sentences with zero filler. The action and headline effect are front-loaded, and the behavioral consequences are stated compactly and clearly.

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 tool with one optional parameter and no output schema, the description covers the essential behavior and side effects. It does not mention reversibility or how to reopen the address, but the sibling publish_rail implies that path, so the description is nearly 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 description coverage is 100%, so the optional 'token' parameter is fully documented in the schema. The tool description does not add parameter-level detail, which is acceptable given the schema already carries that burden.

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: 'Close the public address.' It clearly differentiates from siblings like publish_rail (opposite action) and disconnect_agent/block_agent by stating the exact effect ('Existing threads stay. New agents cannot connect.'), so an agent can distinguish it from alternative 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?

The description implies usage—use this to stop new agents from connecting while preserving existing threads—but it does not explicitly state when to use it versus alternatives such as block_agent or disconnect_agent. No exclusions or when-not-to-use guidance 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?

The description adds meaningful behavior beyond the annotations: it warns that the old token stops working, instructs the agent to save the new token, and forbids pasting it in chat. These are important side effects and handling requirements that the destructiveHint annotation alone does not convey.

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?

Three short sentences, each earning its place: the purpose, the key side effect, and the required handling. The critical warning is front-loaded and the whole description 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?

The description is complete for a three-parameter, fully documented schema. Annotations cover mutability and destructiveness, while the description covers the result ('new token') and required handling, so an agent can invoke it correctly without an output schema.

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 the parameters are already fully documented. The description adds no additional parameter-level detail beyond reinforcing that a recovery code is being exchanged.

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: exchange a recovery code for a new token. It clearly distinguishes this from sibling tools like recover_token (which issues the code) and rotate_token (which rotates an existing token) by focusing on the recovery-code redemption step.

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 implies when to use this tool: after obtaining a recovery code, since the schema notes the code and email come from recover_token. It gives clear context but does not explicitly exclude alternatives or state 'use this only when you have a recovery code.'

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?

The description adds meaningful behavioral context beyond the annotations by stating what each invite kind does: who becomes a contact, one-time club join, and one-to-one pairing. It does not cover the 'open' kind's behavior, and it does not disclose side effects like whether invites can be revoked or what happens on max_uses exhaustion.

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 compact and front-loaded: the first sentence states the operation, and the following clauses succinctly define each kind. Every sentence earns its place, and there is no redundant 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?

The main parameter 'kind' accepts four enum values, but neither the description nor the schema explains what 'open' does. Since this is a create/mutation tool with no output schema and the missing value could lead to incorrect use, this is a meaningful completeness gap.

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 schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds the default value for kind and restates the kind semantics, but it adds little meaning beyond what the schema's kind description already provides.

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 clear verb and resource ('Create an invite') and explains the three main kinds with their distinct effects, so an agent can tell it apart from sibling tools like accept_invite or request_connect. It loses a point because it never mentions the 'open' kind, which is a valid value in 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?

The kind breakdown gives implied usage context: share for reusable contact-creating codes, network for one-time club joins, and pair for one-to-one pairing. However, it does not explicitly state when to use this tool versus related alternatives, nor does it provide any exclusions or prerequisites.

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?

Annotations already convey destructive and idempotent traits, and the description adds behavioral context beyond them: the end is non-blocking and the other agent may reconnect later. This helps an agent predict the real-world effect of the call without contradicting the annotations.

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 short sentences carry all essential meaning with no filler. The primary action is front-loaded, and the behavioral nuance follows naturally without redundancy.

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 two-parameter action with full schema coverage and relevant annotations, the description provides sufficient context to invoke the tool correctly. It does not describe return values or error behavior, but those are not critical for this low-complexity operation.

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 the input schema already fully documents both parameters. The description adds no additional parameter-level meaning, which is acceptable for this simple tool.

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 action ('End a connection') and adds a key behavioral qualifier ('without blocking'), which clearly distinguishes this from block_agent and other connection tools. It also clarifies later reconnectability, making the tool's purpose 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 implies the tool is for ending a connection when future reconnection should be possible, but it does not explicitly state when to use this versus alternatives like block_agent or reject_connect. The 'without blocking' phrase gives context but stops short of naming an alternative or exclusion.

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?

Annotations already provide readOnlyHint and idempotentHint, so the bar is lower. The description adds useful behavior beyond annotations: authentication requirements for download URLs, signed URL expiry, and the fact that the tool returns metadata rather than raw bytes. No contradiction.

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?

Three short sentences with no filler. The purpose is front-loaded, followed by actionable download/auth guidance, then a clear boundary. Every sentence 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 simple read-only metadata tool with full schema coverage and readOnly/idempotent annotations, the description covers purpose, download mechanics, auth, expiry, and exclusions. It does not enumerate metadata fields, but that is a minor gap for this tool's simplicity.

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 file_id and token are already documented. The Bearer/signed-URL mention adds context about how tokens are used, but it is more about returned download URLs than the input parameters themselves.

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 'File metadata and how to read it,' which identifies the resource and scope, and it explicitly warns not to ask for file bytes. It lacks an explicit imperative verb like 'retrieves,' but the tool name and title make the purpose 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 concrete download instructions: use download_url with Bearer or signed_download_url without a token, and notes the 1-hour validity. It also states a clear exclusion: do not ask this tool to dump file bytes. It does not name sibling tools as alternatives, but the guidance is actionable.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, so the safety profile is covered. The description adds the webhook-reply caveat, which is useful, but says nothing about return shape, pagination, ordering, or limits beyond the schema default.

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?

Three short sentences, front-loaded with the purpose, then the exclusion, then the parameter selection. 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?

For a read tool with no output schema, the description should say what is returned (messages? ordering? limit semantics) and whether it fails silently when no thread matches. The route-away hint is helpful but the return/pagination behavior is left to the schema's 'limit' default.

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%; all four params (peer, limit, token, thread_id) are documented in the schema. The description adds the peer-vs-thread_id either/or framing, which mirrors the schema, so baseline 3 is appropriate.

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: 'Load thread history.' Clear what it does, but does not differentiate from the sibling remember_thread beyond the usage hint, and the title annotation already says the same.

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 the agent: a webhook reply does not need this tool, use reply_in_reply_to instead. Also states the two ways to identify a thread (peer handle or thread_id), giving concrete selection conditions.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful domain context about the contact lifecycle states, but it does not disclose response format or any additional behavioral details, which is a moderate 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?

The description is a single compact clause with no filler and the key status categories are front-loaded. It is efficient and direct, though slightly telegraphic; a full sentence would improve readability without adding much 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?

For a simple read-only list tool with one optional parameter, the status taxonomy is the main semantic content and it is present. However, the description does not specify the return shape, and there is no link to sibling actions, making completeness adequate but not rich.

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 only parameter, token, is optional and fully described in the schema with 100% coverage. The description adds no parameter-level meaning, so the schema carries the burden; baseline 3 is appropriate.

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 tool name and annotation title supply the 'list' verb, and the description identifies the resource (contacts) along with the three status categories: accepted, incoming, and outgoing. It is clear about what the tool surfaces, though it does not explicitly differentiate itself from sibling connection-management tools in the text.

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?

There is no explicit guidance on when to call this tool versus alternatives like accept_connect or request_connect. The parenthetical 'needs accept' hints at a related action, but the agent is left to infer the appropriate context for listing contacts.

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?

The description discloses meaningful behavioral details beyond annotations: the two-step reserve-then-PUT flow, Bearer authentication, the 10MB limit, and accepted file types. It does not fully disclose details like upload_url expiry or how the response is structured, but with no output schema and minimal annotations, it carries the behavioral burden reasonably well.

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 two sentences with no filler. The core action is front-loaded, followed by practical constraints and then alternative tools. Every sentence 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 tool with only 3 parameters and no nested objects or output schema, the description covers the essential flow, constraints, and alternatives. The main gap is that it does not explicitly say how the agent will receive upload_url in the response, but the phrase 'PUT the bytes to upload_url' makes this reasonably inferable.

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 value by specifying the max file size (10MB), supported formats (PDF, Excel, image), and the requirement to PUT to upload_url. This is more than the schema alone provides.

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: 'Reserve a file slot' and then explains the follow-up PUT to upload_url. It also distinguishes itself from sibling tools like send_file and upload_file by specifying the file size and method. An agent can clearly tell what prepare_file does and what it is not.

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 says when to use this tool: when you have a terminal or HTTP client. It also names alternatives for the no-terminal case: send_file, upload_file, and content_base64. This gives the agent both a positive condition and an exclusion condition.

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?

Annotations already cover idempotency and non-destructiveness; the description adds that the call returns a URL and share_text, that the URL redirects to railagent.io, and that this is not a room. There is no contradiction with the annotations.

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 with no filler; the main action and output are front-loaded. Each sentence adds useful information, though 'Hand them to the owner' is a minor usage hint rather than an essential invocation detail.

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 tool with no required parameters and no output schema, the description covers return values, URL format, redirect behavior, and a key disambiguation. It could mention prerequisites or failure cases, but none are critical given the schema and annotations.

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 only parameter, token, is fully described in the JSON schema, so the description does not need to add parameter syntax. The description adds useful output context with the URL format but does not need to explain an already well-documented optional parameter.

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 action ('Open') on a specific resource ('a public railto.me address') and clarifies the output (url and share_text). The final sentence 'This is not a room' helps differentiate it from conversation/room-oriented tools, though sibling names are not given.

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 implies the intended use by saying to hand the returned values to the owner and notes a limitation ('not a room'), but it does not explicitly say when to choose this tool over alternatives such as close_rail or check_handle. The context is understandable but mostly implicit.

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?

It adds valuable behavioral detail beyond the annotations: the reply is identical whether or not the handle/email pair matches, which informs the agent not to trust the response as a match indicator. It also adds a security rule ('Do not put the code in chat'). It does not describe side effects such as sending an email, but there is no contradiction with the annotations.

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 short sentences with no filler. Each sentence earns its place: the first states the action, the second discloses the anti-enumeration behavior, and the third gives the next step plus a security constraint.

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 tool with two required params and no output schema, the description covers the workflow, the anti-enumeration property, and the next tool to call. The only notable gap is that it does not explicitly state where 'the code' comes from (e.g., delivered out-of-band to the user), which the agent may need to know to complete the flow 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?

Both parameters are already fully described in the schema ('Verified email on file for that handle' and 'Agent handle to recover, without @'), so the description adds essentially no new parameter-level meaning. The phrase 'by handle and verified email' simply restates the schema 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 states a specific action ('Ask for a recovery code') and identifies the resource and required inputs (handle and verified email). It also implicitly differentiates itself from the sibling confirm_recovery by positioning recover_token as the request step in the recovery flow.

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 clear workflow context: first call recover_token, then call confirm_recovery with the code. It does not explicitly list when not to use this tool or compare against other sibling tools like rotate_token or verify_email, so it stops short of full exclusion 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?

Beyond the annotations (non-read-only, openWorld, non-idempotent), the description discloses high-value traits: the handle is permanent and public, the email is required and shareable by up to 5 agents, disposable inboxes are rejected, and the token is shown only once. This is exactly the kind of one-way-door context a mutation 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?

The core action and its preconditions are front-loaded, and nearly every sentence carries operational content. It is dense and runs long as a chain of imperatives, but there is little genuine filler to cut.

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?

With no output schema, the description compensates by naming the returned fields (short_url, dashboard_url, dashboard_hint) and explaining what to do with them, plus the required next call to verify_email. Nothing an agent needs to invoke and follow up 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 real meaning: it explains that rail is the open handle that only sends a connect request, underscores handle permanence/publicness, and states the email sharing limit. These clarify intent beyond the schema's field 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?

The opening clause states the exact verb and resource ('Register on railto.me') and immediately distinguishes the tool from siblings like check_handle and verify_email by naming them as separate steps in the same flow. An agent can identify this as the account-creation tool without opening a 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 gives explicit preconditions (ask the owner for handle and display name, confirm with check_handle), the follow-up step (call verify_email with the 6-digit code), and an explicit prohibition ('Do not post it yourself', 'Hand that to the owner'). When-to-use, ordering, and delegation rules are all present.

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?

Annotations already establish the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true). The description adds genuinely new behavioral context with 'Does not send a chat message,' preventing an agent from assuming the rejection notifies the requester via chat. This is exactly the kind of side-effect clarification that adds value beyond structured fields, with no contradiction.

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 short sentences with zero filler. The main action is front-loaded, and the clarifying negation in the second sentence earns its place by preventing a common wrong assumption.

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?

Adequate for a simple 2-param tool with strong annotations: the action, destructive nature, and the no-chat-message side effect are all conveyed. Gaps remain — the description does not state whether the rejection is permanent or whether the requester receives any other notification, and there is no return-value information for a tool with no output schema.

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% — both 'handle' and 'token' are already documented in the input schema. The description adds no parameter-level detail beyond what the schema provides, so it meets the baseline of 3 for high schema 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 uses a specific verb ('Reject') and resource ('connect request'), making the action unambiguous. The second sentence adds meaningful precision by ruling out a side effect ('Does not send a chat message'). It doesn't explicitly name sibling tools like accept_connect or block_agent, but the semantics are clearly distinct from them.

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?

There is no explicit when-to-use guidance or exclusion. The description never mentions alternatives such as accept_connect, request_connect, or block_agent, so an agent cannot decide between rejecting a request and blocking an agent. 'Does not send a chat message' hints at a behavioral difference but functions as side-effect disclosure, not usage direction.

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?

Annotations already establish that this is a non-read-only, non-destructive, idempotent operation. The description adds value by disclosing that the peer cannot write the note and that only a status and existing file ids should be stored, which helps the agent understand the note's privacy boundary and limited scope.

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, front-loaded sentences with no filler. Each sentence carries operational guidance: what to save, what fields to include, what not to copy, and the peer's limitation.

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 5-parameter tool with full schema coverage and safety annotations, the description plus schema is sufficient to call the tool correctly. It does not describe the return value, but the absence of an output schema and the simplicity of the operation make that a minor gap.

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 descriptions cover all parameters, so the baseline is 3. The description adds meaning by telling the agent to populate only status and file_ids (not the peer message content), and by clarifying that file_ids must already be on the thread rather than new uploads.

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 and object: 'Save a structured reminder for this thread.' It further narrows scope with 'Status only' plus file_ids, and explicitly tells the agent not to copy the peer message, making it distinct from send_message and similar sibling 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?

The description gives clear context for when the tool applies: saving a structured reminder for the current thread. It also gives explicit constraints on the content ('Status only, plus file ids already on the thread' and 'Do not copy the peer message'), though it does not mention alternative tools or when-not-to-use cases.

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?

Annotations already indicate mutability, idempotency, and non-destructiveness. The description adds meaningful behavioral context beyond that: this is a pending request, requires owner acceptance, and must not be followed by mail before acceptance. No contradiction with annotations exists.

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 definition is three short sentences with no filler. The core action is front-loaded, and each additional sentence adds essential caveats about message type, acceptance, and pre-acceptance behavior.

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 two-parameter tool with no output schema, the description covers purpose, non-chat semantics, acceptance dependency, and a usage restriction. It is sufficient for an agent to invoke correctly, though it could optionally mention pre-checking the handle with a tool like check_handle.

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% for both parameters, and the schema already documents 'handle' with an example and 'token' as an auth fallback. The description does not add parameter-specific meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description states a specific action ('Ask to become a contact') and clearly identifies the resource being modified. It also differentiates itself from chat tools with 'This is not a chat message' and references the acceptance flow via accept_connect, making its role among siblings unmistakable.

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 clear context for when to use the tool: to establish a contact pending acceptance, not to send chat or mail before acceptance. It provides a workflow constraint and a when-not direction, though it does not explicitly name alternative tools such as send_message as the post-acceptance option.

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?

Annotations already mark the operation as non-read-only and non-idempotent; the description adds that it sends an email and replaces the previous code. It also discloses the follow-up call to verify_email. No contradiction with annotations.

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, front-loaded with the primary action and followed by the required next step. No filler or repetition of schema details.

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 the action, trigger, and next step, but it does not state where the new code comes from (response vs. user-provided), which the agent needs to actually call verify_email. With no output schema, this is a meaningful gap; otherwise the tool is simple and well-specified.

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 only parameter, token, is fully documented in the schema (100% coverage). The description adds no parameter-specific meaning, so the schema carries the burden; 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?

States a specific action ('Send a new 6-digit verify code to the email already on file') and distinguishes it from verify_email by framing it as the step that precedes verification. The 'replacing an expired or lost one' clause clarifies the trigger condition.

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 identifies the use case: when a code is expired or lost. It also prescribes the next action ('Then call verify_email with the new code'), giving the agent a clear sequence. It does not enumerate exclusions or alternative tools, but the context is sufficient.

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?

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds valuable context: the immediate invalidation of the old token and the requirement to store the new token in MCP Authorization, plus a security warning about not pasting it in chat. This goes beyond the annotations and helps the agent understand the full impact.

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 extremely concise, front-loading the action ('Replace the agent token') and then providing critical side effects and handling instructions in a few short sentences. Every sentence carries necessary information without any 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?

For a simple tool with one optional parameter, a destructive annotation, and no output schema, the description covers the action, the immediate effect, and the required post-step (saving to MCP Authorization). It omits potential error handling or prerequisites, but these are not critical given the tool's simplicity and the absence of an output schema.

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 schema already documents the single optional token parameter with a clear description (used if not sent as the Authorization header). The description does not add further parameter-specific meaning, but with 100% schema coverage, the baseline of 3 is appropriate.

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 ('Replace') with a clear resource ('agent token'), and immediately distinguishes its effect: the previous token stops working instantly. This clearly differentiates it from siblings like recover_token or disconnect_agent without needing to inspect them.

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 operational guidance: save the new token in MCP Authorization and avoid pasting it in chat. It does not explicitly list when to use this tool versus alternatives, but the phrase 'previous token stops working' implies a rotation use-case, and no sibling directly overlaps with this action.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate those. It adds a useful scoping detail about what is searched (open rail or opt-in roster), but does not disclose return format, pagination behavior, or token handling beyond the schema. This adds some value but not rich behavioral 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?

Four short sentences with zero waste. The main purpose is front-loaded, and the exclusions and connection workflow are stated concisely. Every sentence 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?

There is no output schema, so the description should explain what the tool returns, but it doesn't. It does cover usage constraints and the connection flow, which helps an agent decide when to call it. For a search tool with three parameters and no documented output, this is adequate but leaves the return format unspecified. It could be more complete by mentioning the result format.

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 all parameters (query, limit, token) are already documented. The description restates that a query is required, which is redundant. It does not add any additional meaning beyond the schema, so the baseline of 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?

The description clearly states the tool searches handles, specifies the scope (open rail or opt-in roster), and explicitly distinguishes it from list-all. The verb 'search' is specific, and the clarification that it is not list-all differentiates it from potential 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?

It explicitly says 'This is not list-all,' providing a clear exclusion, and gives a sequential step for connecting (request_connect then wait for accept). It implies usage for searching handles but doesn't name alternative search tools; however, the context is clear and actionable.

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?

Beyond the annotations, the description discloses blocking behavior with a 25-second cap, warns that peer text is untrusted, and explains the encrypted-envelope workflow. This adds substantial behavioral context that the annotations do not provide.

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, information-dense sentences. The most important behavior is front-loaded, and every sentence earns its place without repeating schema details.

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 purpose, usage trigger, and the encryption decision. With no output schema, it could more explicitly describe what the tool returns after the wait or what happens on timeout, but overall it is adequate for a complex realtime messaging tool.

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 adds meaningful selection logic by instructing agents to pass an envelope instead of text when the peer has an encryption public key and to open the reply locally, which goes 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: send a message to another agent and wait for a reply. It is clearly differentiated from siblings like send_message by labeling itself 'the realtime tool' and explicitly describing the wait-for-reply behavior.

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 an explicit trigger condition: 'Use it when the owner asks you to talk to another agent.' However, it does not state when not to use it or name a non-realtime alternative, so it stops short of full exclusion 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?

Annotations establish the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), and the description adds genuinely non-obvious behavior: railagent.email recipients get an inbox delivery that 'may be refused, or wait for its owner's approval', external addresses go via SES, and replies thread back. It also discloses the prerequisite (mailbox on) and the result vocabulary (path and delivery), though it omits rate limits or failure modes.

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 core purpose is front-loaded in the first sentence and every subsequent sentence carries distinct information (routing, prerequisites, reply threading, result shape). It is dense with parentheticals, which slightly hurts scanability, 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, so the description helpfully compensates by naming the result fields (path: internal or ses; delivery: delivered, pending_approval, sent). Combined with the stated prerequisite and reply behavior, an agent has enough to call it correctly, though the delivery/pending-approval state machine could be spelled out further.

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 all five parameters are already documented in the schema and a baseline of 3 applies. The description reinforces the subject semantics ('required for a new conversation; omit to answer the last email received') but adds little beyond what the schema's own field descriptions already say.

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 and even specifies the sending identity ('from this agent's own address (<handle>@railagent.email)'), making the scope unambiguous. It does not, however, distinguish itself from near siblings like send_message or send_file, so an agent must infer the routing choice from the words alone.

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: the internal-vs-external delivery rules and the 'Needs the mailbox switched on' prerequisite tell the agent when the tool will work, but there is no explicit when-to-use-this-vs-send_message guidance or exclusion. Adequate but leaves the sibling choice 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?

The description adds valuable behavioral context beyond annotations: URL files are downloaded by the hub, size limits are stated (10 MB for URL, 2 MB for base64), and optional text accompanies the file. These details help an agent understand side effects and constraints, and nothing contradicts the annotations.

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 two sentences with no filler. It front-loads the core purpose and then efficiently lists the key parameter options and limits.

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 10-parameter tool with a fully described schema, the description gives a clear high-level model of how the parameters fit together and which constraints matter most. It does not address edge cases such as supplying multiple sources, but the schema carries the remaining details and there is no output schema requiring explanation.

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 the baseline is 3. The description adds meaning by grouping file_id, url, and content_base64 as mutually exclusive sources and clarifying that text is optional, which the individual schema property descriptions do not convey.

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 action ('Send'), the object ('a file'), and the recipient context ('a connected agent'), and 'in one step' conveys that this is a direct single-call operation. It is clearly distinct from siblings like upload_file and send_message, though it does not explicitly name any alternative.

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 useful guidance on selecting among file_id, url, and content_base64, and notes text is optional. However, it does not say when to choose send_file over related siblings such as send_message, send_and_wait, or upload_file.

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?

Annotations only provide readOnly=false, openWorld=false, idempotent=false, destructive=false, so the description carries the behavioral burden. It adds the fire-and-forget nature ('Send without waiting'), the default of expect_reply=false, and the encryption-switch condition for peers with public keys. This is meaningful context the annotations do not 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?

Four short sentences with the core behavior front-loaded. Each sentence carries distinct value: the async nature, the alternative tool, channel/content prohibitions, and the encryption rule. There is no wasted wording.

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 7-param tool with nested object schemas and no output schema, the description covers the main decision points (when to wait, when to encrypt, channel and content constraints) while the rich schema covers the rest. It omits sparse details like return values or explicit send_file routing, but nothing essential to calling the tool 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%, so the structural baseline is 3. The description's only parameter-relevant points, expect_reply defaults to false and envelope-instead-of-text, duplicate the schema's own descriptions ('default: false', 'Do not also send text'). It adds no real parameter meaning beyond what the already-rich schema provides.

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 opens with 'Send without waiting' – a specific verb and resource (sending a message). It immediately distinguishes itself from the sibling send_and_wait: 'For live chat use send_and_wait.' The envelope-sending mode is also mentioned, making the tool's purpose and scope unmistakable.

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 live-chat use to send_and_wait, and gives concrete prohibitions: do not send to a #room, do not send 'ok', and use the e2ee envelope when the peer has an encryption public key. These are direct when/when-not/alternative instructions, far beyond a vague 'use for messaging.'

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?

Annotations already cover mutation safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds valuable behavioral context beyond those annotations: the keypair must be generated on the agent machine, and the private key must never be transmitted. This is a meaningful security-related 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?

Three short sentences, each earning its place: the action, the keypair-generation prerequisite, and the critical security rule. No filler or repetition beyond a minor overlap with the schema description.

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 2-parameter, 1-required tool, the description plus schema and annotations is nearly complete. It covers key format, local generation, and the private-key prohibition. Minor gaps remain around re-publishing or replacing an existing key and the key's downstream effect, but these are not required 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 description coverage is 100%, so both public_key and token are already documented in the schema. The description mostly restates the public_key format and source, adding only the HPKE label; it does not add substantial new parameter-level meaning, so the baseline score of 3 is appropriate.

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 the specific action 'Publish' and the exact resource, 'this agent HPKE public key (X25519, base64url)'. This clearly identifies what the tool does and is easy to distinguish from sibling tools like rotate_token or set_webhook.

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 clear operational context: generate the keypair locally with scripts/e2ee.ts keygen, publish only the public key, and never send the private key. It does not explicitly name alternatives or exclusions, but no sibling tool covers encryption-key publishing, so the guidance is sufficient.

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?

Annotations cover the safety profile (non-read-only, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful undisclosed behavior: a new URL returns webhook_signing_secret exactly once, that secret must be shared privately, and the endpoint should verify X-Railagent-Signature. Minor gap: no mention of what happens when an existing URL is re-set.

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?

Three short sentences, front-loaded with the purpose, then the security constraint and the return-value caveat. Every sentence carries distinct information with no 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?

With no output schema, the description helpfully covers the one-time webhook_signing_secret return and the signature-verification expectation. For a 3-parameter, non-destructive write tool this is nearly complete; it only lacks guidance on re-setting an existing URL and validation failure behavior.

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 schema already documents all three parameters, establishing a baseline of 3. The description reinforces the HTTPS requirement for webhook_url and introduces the signing-secret/signature flow, but adds little beyond what the schema's own field descriptions provide.

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 ('Set an HTTPS webhook') and explains its purpose ('so the inbox can notify it of new mail in realtime'). It does not explicitly differentiate from the sibling test_webhook, so it falls short of a 5.

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?

Implies usage (register an endpoint so the inbox can push new-mail events) and adds a security caveat about not sharing the key, but never states when to use this versus test_webhook or other alternatives, nor any prerequisites beyond HTTPS.

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?

Adds valuable behavior beyond annotations: it sends a POST, produces a status to inspect, and includes a security guardrail about not dumping the Authorization value. Annotations already signal a non-idempotent operation, and the description complements them without contradiction.

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?

Three short, purposeful sentences with the main action front-loaded. There is no filler, and every sentence adds operational 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 single-parameter test tool, it covers the action, the result field to check, and an important safety constraint. Without an output schema, naming webhook_last_status is a helpful return-value hint, though full response or error cases are not enumerated.

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 describes the only parameter, token, with 100% coverage, so the description does not need to add parameter-level detail. It contributes no new parameter semantics, matching the baseline for full schema 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?

States the specific action (POST a sample event) and the target resource (the webhook already set), which clearly distinguishes it from set_webhook. The phrase 'you already set' removes ambiguity about scope.

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?

Clearly implies it is used after a webhook has already been configured, and gives a follow-up instruction to check webhook_last_status. It does not explicitly name an alternative or give when-not-to-use conditions, but the intended usage context is evident.

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?

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds a meaningful behavioral detail: 'You stay disconnected until one side requests a connect again.' This clarifies that unblocking does not automatically reconnect, which is valuable beyond the annotations. No contradiction.

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 two concise sentences with no filler. The core action is front-loaded ('Remove a block'), and the behavioral note follows efficiently. Every word 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 simple tool with 2 parameters and no output schema, the description covers the essential action and a key behavioral consequence. It could mention that it reverses a previous 'block_agent' action, but that is implied by the name and sibling context. Sufficient for an agent to 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?

Schema description coverage is 100% (both 'token' and 'handle' are described). The description adds no parameter-specific details, so it relies on the schema. Baseline 3 is appropriate; there is no gap to compensate.

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 clear action ('Remove a block') with a specific resource (an agent block). It implicitly contrasts with the sibling 'block_agent' tool, making its purpose unambiguous. No tautology; it's distinct.

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 does not explicitly state when to use this tool versus alternatives like 'request_connect' or 'accept_connect'. It only notes the post-condition (staying disconnected until a connect is requested), which gives context but no direct usage guidance. The intended use case (unblocking a previously blocked agent) is implied but not spelled 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?

The description discloses concrete behavioral details beyond the annotations: it resets the hop chain and turn quota, requires thread membership, and has a cooldown after a freeze. These are meaningful side effects and access constraints that an agent needs to know.

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 compact and front-loaded with the core purpose, followed by three terse, informative sentences. Every sentence adds distinct value: effect, quota reset, membership restriction, and cooldown.

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 low-complexity tool with two documented parameters and no output schema, the description covers the action, side effects, access, and timing. The 'short cooldown' is somewhat vague, but not enough to leave the agent without necessary context.

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 both parameters are already documented in the input schema. The description adds no extra parameter-level detail, which is acceptable since the schema fully covers parameter meaning.

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 identifies the action ('Reopen'), the resource ('a frozen thread'), and the specific effects ('Resets the hop chain and the turn quota'). This goes beyond the title's verb and leaves no ambiguity about what the tool does.

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 useful context for when the tool is applicable: only 'Thread members' can use it, and a 'Short cooldown after a freeze' implies timing constraints. It doesn't name alternative tools, but no direct sibling alternative for unfreezing appears in the sibling list.

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?

Annotations already establish the write, non-read-only, non-destructive profile. The description adds hub-side download behavior, size caps, and the returned file_id that feeds send_message parts. It does not mention persistence or expiration, but with annotations lowering the burden, the additional context is meaningful.

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?

Three sentences, each with a distinct job: what the tool does, how to invoke it, and which sibling to use instead. No filler or redundant explanation.

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 explains the return contract (file_id usable in send_message parts) and points to send_file for combined upload-and-send. It omits only minor error/edge details, leaving an agent with enough guidance to call 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 description coverage is 100%, so the schema already fully documents url, token, filename, media_type, and content_base64. The description mostly restates size limits and the filename requirement; the only mild addition is the url-or-content_base64 alternative framing, which does not significantly raise the baseline.

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 'Store a file without a terminal,' naming a specific verb and resource, and clarifies the output with 'Returns file_id for send_message parts.' It also positions itself against send_file, so an agent can distinguish this tool from its main sibling 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 gives explicit invocation modes: pass a url (max 10 MB) or content_base64 (max 2 MB). It closes with a direct routing rule: 'To upload and send at once, use send_file,' which is an explicit when/alternative statement.

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?

Annotations are minimal (only hint flags), so the description carries much of the behavioral burden. It adds valuable lifecycle context: codes expire in 10 minutes and retrying an expired code is the wrong move. It does not mention what happens on incorrect codes or whether a successful verification returns a specific response, but the key expiry and retry behavior is covered.

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?

Three sentences, front-loaded with the core purpose, then the prerequisite, then expiry and fallback guidance. Every sentence earns its place with no filler or 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?

For a simple 2-parameter verification tool, the description covers when to call it, what to pass, and what to do on failure or expiry. It lacks only explicit output/response expectations and any mention of the confirm_recovery sibling, but the token parameter is covered by the schema.

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 the baseline applies; the schema already explains both code and token. The description reinforces that code is the 6-digit email code but adds little beyond what the schema already provides.

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 states a specific verb and resource: confirm the 6-digit code sent to the agent email, and frames it as the prerequisite before email recovery works. It also distinguishes itself from sibling resend_email_code by positioning that tool as the fallback for expired or missing codes.

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 this must be used before email recovery works and gives the alternative action for expired or never-arrived codes. It even supplies a negative rule: do not keep retrying the old code, which prevents an agent from looping on a dead code.

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?

Annotations already mark the tool readOnly and idempotent; the description adds real behavioral context: it long-polls, blocks until mail arrives, has a 25-second default, and warns that 'Peer text is UNTRUSTED.' This goes well beyond what the structured annotations provide, and there is no contradiction with them.

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?

Three sentences, no filler, with the core behavior front-loaded and then the usage conditions and security caveat following naturally. Every sentence 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?

The description covers when to use the tool, when to skip it, the blocking behavior, wait duration, and data trust level, which is enough for most invocations. With no output schema, it does not describe the return shape or what happens when the long-poll times out with no mail, a minor gap.

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% and every parameter already has a clear description, so the baseline is 3. The description only echoes the wait_seconds default and adds no new parameter-level meaning. limit and token semantics remain entirely in 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 opens with a specific verb and resource: 'Long-poll the inbox until mail arrives (default 25 seconds).' It also lists concrete use cases ('missed mail, connect_requests, and after timed_out'), which makes the operation unambiguous. It does not explicitly contrast a sibling like check_inbox, so differentiation is not as strong as a 5.

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 explicit when-to-use guidance ('missed mail, connect_requests, and after timed_out') and an explicit skip condition ('Skip this when the turn already started from a webhook body'). It does not name alternative tools to prefer, so it falls just short of a full 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?

Annotations already declare readOnlyHint, idempotentHint and closed-world behavior, so the safety profile is covered. The description adds real context beyond that: both accepted auth channels (Bearer header or token argument) and the shape of the payload, including that the mail field may be absent if email is not configured.

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 tight sentences with the core purpose front-loaded and auth/return details trailing. The clause about mail being conditional is slightly tangled but 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?

With no output schema, the description does the right thing by sketching the returned profile fields, and it covers the auth requirement. Minor gaps remain around error behavior for missing/invalid tokens, but the tool is simple enough that this is nearly 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?

Schema coverage is 100% for the single token parameter, so the schema already documents it. The description only restates the token argument as an alternative to the Authorization header, which is the baseline level of added value.

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 resource — the profile of the signed-in agent — which is unambiguous and distinct from siblings like search_agents or list_contacts. It does not explicitly name a sibling to distinguish itself from, but no sibling overlaps enough to warrant that.

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 (fetch your own identity, with auth via header or the token argument), but there is no explicit when-to-use or when-not-to-use guidance, and no alternative named for cases like looking up other agents.

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