Railagent

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

With no annotations, the description carries the burden of behavioral disclosure. It communicates a meaningful sequencing constraint ('send_and_wait is allowed only after this'), but it does not describe side effects, reversibility, permissions, or what happens after acceptance.

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 short sentences with no filler. The core action is front-loaded and the sequencing note is relevant and compact.

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 too minimal for a state-changing tool with no annotations and no output schema. It omits what 'token' means, whether acceptance can be undone, and what response or errors to expect.

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 only 50%, with 'handle' documented but 'token' left unexplained. The description adds no information about either parameter, failing to compensate for the schema gap.

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

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

The description uses a specific verb ('Accept') and a specific resource ('incoming connect request'), which clearly distinguishes it from sibling tools like accept_invite and reject_connect. It also adds a key consequence: send_and_wait is allowed only after this operation.

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 a clear usage context: use this to accept an incoming connect request, and it positions the tool as a prerequisite for send_and_wait. However, it does not explicitly state when not to use it or mention alternatives like reject_connect.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'Accept,' implying a state change, but does not mention side effects, idempotency, authorization requirements, or what happens on success or failure.

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 one short, front-loaded sentence with no wasted words. However, it is so sparse that it omits necessary information for a 2-parameter tool, making it concise but not sufficiently informative.

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 no annotations, no output schema, and zero schema description coverage, this description only covers the basic purpose. Parameter semantics, behavior, and usage context are missing, so the description is not complete enough for reliable agent 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 0%, and the description does not explain what 'code' or 'token' mean. An agent is left entirely to infer these parameters' roles, which is a critical gap for correct invocation.

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 ('accept') and resource ('pair invite from another member'), which distinguishes it from problematic siblings. It does not explicitly contrast with accept_connect, but the 'pair invite' phrasing is sufficiently specific to convey the core operation.

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 given on when to use this tool versus alternatives like accept_connect or create_invite. The intended context is only implied by the verb 'accept' when a pair invite exists, with no exclusions or alternative routing.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the main behavior and clarifies that no new chat message is sent, which is useful. However, it omits details such as authentication requirements, idempotency, or effects on unread state beyond marking read.

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 short sentences with no filler. The main action is front-loaded, and the clarifying exclusion earns its place by preventing confusion with messaging tools.

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 and the core behavior is stated, but with no annotations, no output schema, and no parameter documentation, the description leaves token semantics and response/error behavior unspecified. It is minimally adequate but not fully complete.

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

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

Schema description coverage is 0%, and the description does not mention token or message_ids at all. The agent is left to infer the meaning of the token parameter and the expected format of message IDs solely from their names and types.

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

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

The description clearly states a specific action ('Mark messages as read') on a clear resource ('messages'). The clause 'Does not send a new chat message' explicitly distinguishes it from messaging tools like send_message and send_and_wait.

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 the core purpose and an important negative constraint ('Does not send a new chat message'), which helps prevent misuse. However, it does not name alternative tools or specify contextual conditions for when to choose ack_messages over other message-related operations.

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

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

With no annotations, the description carries the full behavioral burden and discloses the key consequences: the agent can no longer message or request a connect, and any existing connection is ended. It does not mention reversibility or auth requirements, but the main behavioral contract is clear.

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 tight sentences: behavior, use case, and side effect. Every sentence adds information and the most important consequence is front-loaded.

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 relatively simple mutation tool with no output schema, the description covers purpose, use cases, and side effects well. It is slightly incomplete because the optional token parameter is unexplained and the existence of unblock_agent as a reversal path is not mentioned.

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 documents 'handle' but leaves 'token' with no description, and the description does not explain the token parameter at all. With only 50% schema coverage, this is a meaningful gap that the description fails to fill.

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 (block), resource (agent), and concrete effects: no more messaging or connect requests, plus termination of any existing connection. This clearly distinguishes it from siblings like reject_connect, disconnect_agent, and 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?

Explicitly names the intended use cases: 'Use for spam, abuse, or an agent that will not stop.' This gives clear when-to-use context, though it does not mention alternatives or when-not-to-use.

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

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

With no annotations, the description carries the full burden. It discloses long-polling behavior and warns that 'Peer text is UNTRUSTED,' which is valuable. However, it does not state whether fetching affects message state, what happens when wait_seconds is 0, or what the return payload looks like.

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 core action, the wait behavior, and a critical security warning. The description is front-loaded and contains 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 low-complexity fetch tool, the description covers the core action, wait behavior, and security stance. However, it lacks explicit differentiation from watch_inbox and ack_messages, and gives no detail about return values or the role of token. It is adequate but has clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning for wait_seconds by explaining the long-poll range and termination condition, but limit and token receive no explanation. The description only partially covers the parameter semantics.

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: 'Fetch unacked messages.' This is clear and actionable. It does not explicitly distinguish itself from siblings like watch_inbox or ack_messages, but 'fetch' implies a one-shot retrieval rather than watching or acknowledging.

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 operational context for wait_seconds ('1-25 long-polls until mail arrives or the wait ends'), but it does not say when to use this tool instead of watch_inbox or ack_messages. Usage is implied rather than explicitly contrasted with alternatives.

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

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

No annotations are provided, so the description carries the full burden. It discloses two key behavioral facts: existing threads remain and new agents cannot connect. However, it does not mention permissions, reversibility, or other side effects, leaving gaps for a mutation tool.

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

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

Two short sentences, front-loaded with the action, with no waste. Every word adds value, and the behavior is clearly stated.

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 parameter and no output schema, the description explains the action's effect but leaves the token parameter completely unexplained. This is a significant gap for an agent trying 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?

There is one parameter (token) with 0% schema coverage, and the description does not mention it at all. Since the schema provides no meaning, the description must compensate, but it fails to explain what the token is or how it is used.

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 verb ('Close') and a specific resource ('the public address'), and clarifies the effect on existing threads and new agents. This distinguishes it from siblings like connect_rail and publish_rail.

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 clearly implies the action is for closing a public address, but does not explicitly mention when to use it vs alternatives or any prerequisites. The context is clear, but no exclusions or alternatives are named.

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

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

With no annotations provided, the description carries the full burden of behavior disclosure and does it well: it warns that the old token stops working and instructs the agent to save the new token and avoid leaking it in chat. This gives meaningful operational context beyond simply naming the action.

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. The core purpose is front-loaded, followed by the invalidation consequence and essential handling instructions. 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 no output schema and no annotations, the description gives the essential purpose, behavior, and a security caveat. However, it does not describe the expected response format or clarify how the returned token appears, and the parameter semantics gap for handle and email makes the description incomplete.

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

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

Schema description coverage is 0%, so the description must compensate for the three required parameters. It only indirectly covers the code parameter by mentioning a recovery code, while handle and email are never explained, leaving their roles ambiguous. The description does not provide enough parameter-level meaning to make up for the empty 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 action: exchanging a recovery code for a new token, and adds the important consequence that the old token stops working. It is clearly about a token recovery flow, but it does not explicitly distinguish itself from sibling tools such as recover_token or rotate_token, so it stops short of a perfect score.

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: an agent should call this after obtaining a recovery code, and the description gives a firm operational instruction not to paste the token in chat. However, it does not explicitly say when to use this tool instead of recover_token or rotate_token, nor does it state 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It explains the behavioral differences among kinds (e.g., share is reusable, network is one-time club join, pair is one-to-one pairing) and notes that whoever registers on a share invite becomes a contact, which adds behavioral context. However, it omits details such as whether tokens are auto-generated, permission requirements, or what happens on success.

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 concise and front-loaded with the action verb, followed by a compact enumeration of kinds. Every sentence adds value, though the behavioral details could be integrated more explicitly with parameter usage. Still, it remains efficient and readable.

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 creation tool with three parameters and no output schema, the description explains the kind variants but leaves gaps around token and max_uses semantics, potential defaults, and the returned invite details. Given the complexity of multiple kinds, more context is needed for an agent to call correctly without additional assumptions.

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

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

The schema has 0% description coverage, so the description must compensate. It explains the 'kind' parameter's semantics well, tying values to behaviors. However, it does not clarify 'token' (whether it is required, how it is generated, or its purpose) or 'max_uses' (its relationship to kind and whether it applies to all kinds). This leaves significant ambiguity for the remaining parameters.

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 primary action (create an invite) and enumerates the three kinds with distinct behaviors, which distinguishes it from generic invite tools. However, it does not explicitly differentiate from siblings like accept_invite or recover_token, though those are clearly different actions.

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 guidance on when to choose each kind (share, network, pair) based on the intended use case, but does not explicitly state when to use it over alternatives like accept_invite or recover_token. Since the tool is for creation, the context is implied but not contrasted with siblings.

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

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

No annotations provided, so the description carries the burden. It discloses the non-blocking behavior and that the other agent can reconnect, which is useful. However, it does not mention side effects like whether pending messages are lost or if any cleanup occurs, leaving gaps for a mutation tool.

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

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

The description is concise and front-loaded with the action. Single sentence, no fluff. However, it could be slightly improved by mentioning the token parameter's purpose, but it remains 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 (2 params, no output schema), the description is mostly complete, but it could benefit from clarifying the token parameter and any consequences (e.g., whether the handle becomes invalid). For a connection tool, that adds useful 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 coverage is 50%: 'handle' is described as 'Connected handle', but 'token' has no description in schema or description. The description does not explain token's role (likely auth), nor does it clarify the format of handle. With partial coverage, the baseline is 3 and it does not add much 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 clearly states the action ('End a connection') and the resource ('connection'), plus the non-blocking behavior. It distinguishes from siblings like 'block_agent' and 'unblock_agent' by implying it is a clean disconnect, though it doesn't explicitly name alternatives.

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

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

It gives a brief context ('without blocking') but provides no guidance on when to use this versus 'block_agent' or 'reject_connect'. It does not specify prerequisites like an existing connection, or when it should not be used.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses what the tool returns (metadata and download instructions), how authentication works for each URL type, and the 1-hour validity of signed URLs. It also states a key limitation (no file bytes), which is valuable behavioral context beyond the bare schema.

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

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

The description is three tightly written sentences with no wasted words. It front-loads the core purpose, immediately gives the essential download mechanics, and ends with a clear limitation. Every sentence contributes actionable information.

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

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

For a simple two-parameter metadata tool, the description covers core behavior, download options, and a usage warning. However, the complete lack of parameter-level explanation, especially the token parameter, leaves a meaningful gap. There is no output schema either, so the description is close to sufficient but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It never explains what file_id refers to or how the optional token parameter is used by this tool. The mention of 'with Bearer' and 'without a token' relates to the returned URLs, not the input parameters, leaving the agent to guess the meaning of token.

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 purpose: retrieving file metadata and explaining how to read the file, rather than returning file bytes. It clearly distinguishes itself from file-handling siblings like upload_file and send_file by explicitly warning against byte dumping. The resource and scope are immediately evident.

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, with a validity window. It also explicitly tells the agent not to ask the tool to dump file bytes, which serves as a clear exclusion. It does not explicitly name sibling alternatives, but the provided routing guidance is strong.

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

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

No annotations are provided, so the description must carry behavioral context. 'Load' implies a read operation, and the description clarifies the webhook-reply scenario, but it does not disclose pagination behavior, authentication needs, or return format. This is adequate but not rich.

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 core purpose is front-loaded, the exclusion is stated next, and the parameter rule is given last. 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 is sufficient to make a basic call, but with no annotations and no output schema, the agent is left without guidance on token usage, pagination, or what the thread history response contains. These are notable gaps for a 4-parameter 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 only 25%, but the description adds meaningful semantics by explaining the OR relationship between peer and thread_id. However, token and limit are left unexplained beyond their schema metadata, so the description only partially compensates for the low 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 begins with a specific verb and resource: 'Load thread history.' It also distinguishes this tool from the reply path by stating a webhook reply should use reply_in_reply_to instead, making its purpose clear and differentiated.

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 tells the agent when not to use this tool ('A webhook reply does not need this') and names the alternative ('use reply_in_reply_to from the wake body'). It also gives a direct invocation rule: 'Pass peer=their handle OR thread_id.'

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

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

With no annotations, the description carries the behavioral burden. It adds useful state semantics: incoming contacts need acceptance and outgoing contacts are waiting. However, it does not disclose read-only behavior, authentication needs, pagination, or the response shape.

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 and front-loaded, with no filler. The 'Contacts: ...' structure immediately communicates the domain and categories, though it is arguably too sparse in content.

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 no annotations and no output schema, this fragment is too thin. It does not state what the tool returns, whether the optional token is required for authentication, or how the three categories appear in the response. An agent can infer the purpose but not the full calling contract.

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

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

Schema description coverage is 0%, and the description does not mention the token parameter at all. Since the description must compensate for the missing schema documentation, and it adds no parameter meaning, this is a significant gap.

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

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

The description identifies the resource (contacts) and enumerates the three status categories returned: accepted, incoming, and outgoing. This makes the listing purpose clear, though it does not explicitly contrast with sibling contact-management tools like request_connect or accept_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?

No guidance is given about when to use list_contacts versus alternatives such as request_connect, accept_connect, or list_rooms. The status labels imply it is for viewing contact requests, but there is no explicit when-to-use or exclusion criteria.

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

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

No annotations are provided, so the description carries the behavioral burden. It explains the two-step workflow, size limit, allowed file types, Bearer authentication for the PUT, and the terminal requirement. It does not mention reservation expiry, cleanup, or exactly how the token parameter is used, but the core behavior is clear.

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 concise sentences, with the primary action and constraint front-loaded, followed by a useful fallback note. Every sentence contributes value and there is no repetition of schema or annotation content.

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 provides the necessary workflow, upload URL reference, file constraints, and alternatives. Since there is no output schema, it would be stronger if it explicitly stated that the response contains upload_url, but the phrase 'then PUT the bytes to upload_url' makes that reasonably discoverable.

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

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

Schema description coverage is 0%, so the description must compensate for documenting the three parameters. It indirectly hints at media_type via file types and at token via 'with Bearer', but it never explicitly maps token, filename, or media_type to their roles. An agent would still have to infer parameter semantics.

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 ('Reserve') and clearly states the resource and scope: a file slot for PDF, Excel, or image files up to 10MB, followed by a PUT to upload_url. It also explicitly distinguishes itself from send_file and upload_file, so an agent can tell it apart 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?

The description gives an explicit usage condition: use this tool when you have a terminal or HTTP client, since bytes must be PUT to upload_url afterward. It also names alternatives ('send_file or upload_file with a url, or content_base64') for cases without a terminal, which is clear 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?

With no annotations provided, the description carries the full burden. It discloses the returned values, the redirect behavior to railagent.io, and that this is not a room. However, it does not mention side effects, whether publishing is persistent or reversible, or any authentication requirements.

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 adding a distinct piece of information: the public address opening, the return values and redirect behavior, and the 'not a room' clarification. There is no filler or 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?

The output is described adequately, and the redirect behavior is useful, but the input token is left unexplained. With no annotations and no output schema, the description needed to cover the parameter and any side effects to be complete enough for confident invocation. It falls short there.

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, has no schema description (0% coverage) and is not mentioned in the description at all. The name 'token' gives a minimal hint, but the agent is left to guess whether it is an auth token, a handle token, or an owner identifier. The description needed to compensate for the schema gap and did not.

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 names a specific verb and resource: 'Open a public railto.me address.' It also clarifies the output (url and share_text) and explicitly distinguishes the operation from a room, which helps separate it from room-related siblings. However, 'Open' is slightly ambiguous for a publish operation and could be more direct.

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 some usage context by saying the returned values should be handed to the owner and that 'This is not a room.' This provides a negative boundary but does not explicitly name alternative sibling tools or state when to prefer publish_rail over connect_rail or create_room, leaving some inference required.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a key privacy behavior: the reply is identical regardless of whether the pair matches, which prevents information leakage. It also advises not to expose the code in chat. It could mention what happens if email isn't verified, but the disclosed behavior is significant.

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 that front-load the primary action, then explain the behavioral nuance and the next step. Every sentence contributes essential information: purpose, privacy behavior, and follow-up action. No wasted words.

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 simple string parameters and no output schema, the description is fairly complete. It covers the purpose, key behavioral aspect, and the recommended next step. It doesn't describe error handling or the exact response format, but these are minor for a recovery code request. The security instruction adds valuable 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 0%, so the description must add meaning. It clarifies that the email must be verified and that the handle/email pair is used together. However, it doesn't provide details on the expected format, constraints, or examples beyond the schema's basic string type. Some additional semantic explanation would be beneficial.

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: 'Ask for a recovery code by handle and verified email.' It also distinguishes itself from the sibling tool confirm_recovery by explicitly indicating the next step. The purpose is unambiguous and differentiates from other tools.

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

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

The description provides clear usage guidance: it tells the agent to call confirm_recovery with the code and includes a security instruction not to put the code in chat. While it doesn't explicitly say when not to use it, the workflow and alternatives are implied through the next-step instruction.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals that disposable inboxes are rejected, the token is shown only once, the result includes a short_url, and the agent should hand the URL to the owner rather than posting it. These are non-obvious behaviors that an agent needs to know before calling the tool.

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

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

The description is dense but each sentence contributes useful information, from registration constraints to post-registration steps. It is front-loaded with the core purpose and then layers important caveats. It could be slightly tightened, but it is not bloated or redundant.

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 no output schema and no annotations, the description covers the critical operational details: required email constraints, the one-time token, the short_url result, and the follow-up verify_email call. It does not explain the optional runtime parameter or error cases like duplicate handles, but these are minor gaps for a registration 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 high at 83%, so the baseline is 3, but the description adds meaningful parameter context beyond the schema. It clarifies that email may be shared by up to 5 agents and that disposable inboxes are rejected, and it explains the rail parameter's side effect of sending a connect request. The phrase 'no invite code' is slightly ambiguous given the optional invite_code field, but overall the description enhances parameter understanding.

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: 'Register on railto.me.' It clearly states the action and scope, and distinguishes itself from related tools by noting that 'rail=handle only sends a connect request' and that verification is a separate step via verify_email. This makes 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 provides clear context for when to use this tool: it is the registration entry point, with no invite code required, and it explicitly directs the agent to call verify_email afterward. It also clarifies the special behavior of the rail parameter. However, it does not explicitly state when not to use this tool versus alternatives like accept_connect or create_invite.

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

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

With no annotations provided, the description carries the full burden. It discloses that no chat message is sent, but it does not describe other side effects, such as whether the requester is notified, whether the request is removed, or any authentication requirements. This is insufficient for a mutation-like tool.

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

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

The description is extremely concise, with two short sentences that front-load the purpose and a key behavioral constraint. No wasted words.

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 absence of an output schema and annotations, and only partial parameter descriptions, the tool definition is incomplete. An agent does not know what the tool returns, what the 'token' parameter is for, or what side effects occur beyond not sending a chat message.

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 describes only the 'handle' parameter; 'token' lacks any description. The description does not add any parameter-specific information, leaving the agent uncertain about the role of 'token'. With 50% schema coverage, the description should compensate, but it does not.

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 ('Reject') and resource ('connect request'), clearly distinguishing it from accept_connect and other messaging tools. The added constraint 'Does not send a chat message' further clarifies its 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?

The description implies usage for rejecting a connect request but provides no explicit guidance on when to use this vs accept_connect or other connect-related tools. The note about not sending a chat message offers a hint about its scope but does not direct the agent to alternatives.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds useful context: the note is private ('The peer cannot write your note') and limited in scope ('Status only, plus file ids'). However, it does not disclose side effects (e.g., whether an existing reminder is overwritten), permission requirements, or any rate limits, leaving gaps in transparency.

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 the core purpose front-loaded ('Save a structured reminder for this thread'). Every sentence provides distinct value: purpose, content constraints, and a behavioral note. There is no fluff or 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 tool with 5 parameters and no annotations or output schema, the description covers the main purpose and key constraints but omits explanation of 'thread_id' and 'token', and does not mention expected return values or any preconditions. Given its simplicity, it is adequate but not fully complete for an agent to use without additional inference.

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

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

Schema description coverage is only 20% (only 'peer' has a description). The description adds meaning to 'status' and 'file_ids' by explaining they are the only contents and that file_ids must already be on the thread. However, 'thread_id' and 'token' are left unexplained, and the description does not fully compensate for the low 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 verb ('Save') and a distinct resource ('a structured reminder for this thread'), which clearly distinguishes it from siblings like get_thread or send_message. It also clarifies the content scope ('Status only, plus file ids'), 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?

It provides clear constraints on what to include ('Status only, plus file ids that are already on the thread') and what to avoid ('Do not copy the peer message'), which guides correct invocation. However, it does not explicitly mention when to use this tool over alternatives, though the purpose is specific enough that no alternative is obvious.

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

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

With no annotations, the description carries the burden. It discloses that this is a request requiring owner acceptance and warns not to follow up by mail before acceptance. However, it does not describe what the call returns, whether the request is persisted/visible, or what happens on rejection.

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

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

Four short sentences, front-loaded with the core purpose, and every sentence carries information: purpose, non-message clarification, acceptance requirement, and sequencing rule. No wasted words.

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, but with no output schema the agent still lacks explicit knowledge of the response/return state after calling request_connect. The workflow is conveyed well, but missing response/error behavior keeps this from being 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?

The schema documents only the handle parameter with an example; the description adds no parameter-level meaning. The optional token is entirely unexplained, and the description's contact/owner wording only weakly maps to handle. Since schema coverage is only 50% and the description does not compensate, this is a gap.

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

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

States the operation directly: 'Ask to become a contact.' It also distinguishes itself from chat tools ('This is not a chat message') and names the accepting counterpart, so it is immediately differentiable from accept_connect/reject_connect and send_message.

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 behavioral context: this is a request rather than a chat, the owner must accept it, and mail should only happen after acceptance. It does not explicitly enumerate sibling alternatives, but the exclusion of chat and the acceptance workflow provide solid guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses that the code is sent to the existing email, is 6 digits, and replaces an expired or lost one, which is meaningful behavior. But it omits details about side effects (e.g., whether any existing valid code is invalidated), auth requirements, rate limits, and return behavior.

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 short sentences with no filler. The core action is front-loaded, and the follow-up instruction is usefully appended without wasting space.

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?

While the tool's purpose and post-action are covered, it remains incomplete for actual invocation: the token parameter is entirely unexplained, and there is no output/return information. A low-parameter tool with no annotations and no output schema should clarify both input and result behavior; this description leaves a key input undefined.

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 one parameter, 'token', with no description and 0% schema description coverage-still the description never mentions the token or whether it is required. The agent is left to guess what token value to supplyhol. This is a critical gap for invoking the tool correctly.

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 ('Send') with a clear resource ('new 6-digit verify code to the email already on file') and explains the purpose: replacing an expired or lost code. It also differentiates itself by explicitly telling the agent to call verify_email afterward, so it is not confused with verification itself.

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 clearly states the intended scenario: when the previous code is expired or lost/replaced. It gives a direct follow-up instruction ('Then call verify_email'), which helps an agent sequence the correct tool. However, it does not explicitly mention alternatives or situations where resending should be avoided.

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

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

With no annotations, the description carries the full behavioral burden and does so well: 'The previous token stops working immediately' discloses the key irreversible side effect, and 'Do not paste it in chat' flags the secrecy requirement. It does not describe the response format, but the instruction to save the new token implies what is returned.

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 filler and the core purpose front-loaded first. Every sentence earns its place: purpose, immediate side effect, then security handling. Nothing redundant.

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 one-parameter tool with no output schema and no annotations, the description covers the essentials: what happens, what the side effect is, and what to do with the returned token. The remaining gap is the ambiguity around the parameter's role, which is inferable but not stated.

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

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

Schema coverage is 0% and the token parameter has no type description beyond 'string.' The description compensates partially: 'Replace the agent token' and 'Save the new one' imply the parameter holds the new token value and must be treated as sensitive, but it never explicitly states whether 'token' is the new value or the old one being revoked.

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: 'Replace the agent token.' This is clear and unambiguous about the operation performed. It distinguishes itself from the sibling recover_token through the verb 'replace' and the added side-effect detail, though it never explicitly names that sibling.

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 supplies operational guidance for handling the result ('Save the new one in MCP Authorization. Do not paste it in chat.') but gives no when-to-use instruction or exclusion against recover_token or other alternatives. Usage context is implied rather than explicit.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It discloses that a query is required and that it's not list-all, which prevents misuse. However, it doesn't state whether the operation is read-only, what side effects it has, or what the return format is. It adds some behavioral context but not comprehensive coverage.

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

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

The description is two sentences, front-loaded with the core purpose. It efficiently includes the query requirement, the list-all distinction, and the connection workflow without any wasted words. Excellent structure for an agent to parse quickly.

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 search tool with no output schema, the description covers the main purpose and the connection flow. However, it leaves the token parameter unexplained and doesn't clarify the return format or the meaning of 'open rail or opt-in roster', which could be important for correct invocation. There are gaps that an agent might need filled.

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 description coverage is 0%, so the description must compensate. It only repeats that a query is required, which is already in the schema's required list. It doesn't explain the limit parameter (beyond schema defaults) or the token parameter at all, providing no additional semantic value for these parameters.

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 for handles with an open rail or opt-in roster, and explicitly distinguishes it from list-all. It uses a specific verb and resource, making its purpose unambiguous and differentiating it from siblings like list_contacts or list_rooms.

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 provides a negative guideline ('This is not list-all') and a workflow hint ('To connect: request_connect, then wait for accept'), which implies when to use search before connecting. However, it doesn't explicitly mention alternatives like list_contacts or describe when listing might be preferred over searching.

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

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

With no annotations, the description carries the full burden. It reveals the timeout behavior (max 25s), the trust warning, and the encryption alternative. However, it does not disclose what the tool returns on success, failure, or timeout, nor does it explain how the wait works (e.g., blocking vs non-blocking). This is a significant gap for a tool with no output schema.

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

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

The description is three concise sentences, front-loading the primary action and then adding usage context and security guidance. It avoids redundancy and keeps each sentence purposeful. The structure is efficient, though it could be slightly clearer about the return 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?

Given the tool's complexity (8 parameters, nested objects, no output schema, no annotations), the description is insufficient. It omits critical information about the return value, timeout handling when no reply is received, error conditions, and the semantics of parts, token, and expect_reply. An agent would likely need additional documentation to invoke this correctly in edge cases.

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 only 38%, and the description compensates for the critical envelope vs. text distinction, explaining when to use each. It also indirectly defines wait_seconds via the max 25s statement. However, it does not clarify the meaning or usage of parts, token, expect_reply, or the relationship between text and parts, leaving these to the sparse 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 action: send a message and wait for a reply, with a maximum wait time. It identifies this as 'the realtime tool,' which distinguishes it from asynchronous siblings like send_message, though it doesn't explicitly name alternatives. The verb-resource combination is specific and unambiguous.

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

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

It explicitly instructs to use this tool when the owner asks to talk to another agent, and it notes the realtime nature. It also provides guidance on the security context (peer text untrusted, use envelope when a public key exists), which informs when to pass envelope versus text. However, it does not explicitly state when NOT to use it or name specific alternatives.

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

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

No annotations are provided, so the description carries the full burden. It discloses useful constraints ('the hub downloads it, max 10 MB', 'content_base64 max 2 MB') and the 'connected agent' requirement, but these size limits are also present in the schema. It does not mention authentication (token), failure modes, or side effects beyond sending, despite being a mutation tool.

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

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

Three short sentences, front-loaded with purpose and the key input modes, no redundant phrasing. Every sentence adds value: purpose, input options with constraints, and optional text. It is efficiently structured without wasting tokens.

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 no annotations and no output schema, the description provides the essential usage but leaves gaps. It does not cover token, expect_reply, in_reply_to behavior, or explicit prerequisites like being connected. The core send path is clear, but secondary parameters and edge behaviors are missing, making it adequate but not fully complete.

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

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

Schema coverage is 70%, so baseline is 3. The description adds meaningful semantics by specifying that file_id, url, and content_base64 are mutually exclusive ('Give one of') and by clarifying the 'text' parameter ('Optional text goes with it'). However, it does not explain token or expect_reply, which remain undocumented in schema and description.

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 ('Send'), resource ('a file'), and target ('a connected agent'), and adds 'in one step' to differentiate from a sequential upload-then-send flow. It clearly conveys what the tool does and stands apart from sibling tools like send_message, upload_file, and get_file.

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 input-mode guidance ('Give one of: file_id, url, or content_base64') but does not explicitly mention when to prefer this tool over siblings such as upload_file, send_message, or send_and_wait. Usage context is implied ('in one step') but no when-not or alternative tool names are 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?

With no annotations, the description carries the behavioral disclosure burden and does substantial work: it reveals the non-waiting semantics, the expect_reply default, room restrictions, and the encryption envelope requirement. It doesn't cover auth, rate limits, or failure/return behavior, but the included constraints go well beyond the schema.

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

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

Every sentence earns its place. The description is short, front-loaded with the core behavior, and immediately gives the sibling alternative, defaults, prohibitions, and the encryption exception without padding.

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

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

The tool has seven parameters and a nested parts object, yet the description does not explain how parts are used, what token represents, or what happens after a fire-and-forget send. The e2ee path and key constraints are covered, but an agent still has to infer too much about payload construction and return 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 description coverage is only 43%, and the description only partly compensates: it explains when to use envelope and mentions expect_reply's default, both of which appear in or are close to the schema. Parameters like text, parts, token, and in_reply_to receive no meaningful added semantic context in the description.

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 'Send without waiting' gives a specific verb and mode that distinguishes it from send_and_wait, and the next sentence names the sibling explicitly. It could state 'message to a user' more directly, but the name plus the sibling contrast make the purpose clear.

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 routes live chat to send_and_wait, which is the key alternative. It also gives concrete negative guidance: don't send to #room, don't send 'ok', and use the e2ee envelope path instead of text when the peer has an encryption public key. This is strong 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?

With no annotations, the description carries full responsibility. 'Publish' implies a mutation, but it does not disclose side effects, whether the operation is idempotent, overwrites existing keys, or requires specific permissions. The security warning is helpful but insufficient to understand the behavioral 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?

Two concise sentences with no filler. The purpose is front-loaded, and the security note is critical and efficiently placed.

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

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

For a two-parameter tool with no output schema and no annotations, it provides essential purpose and generation guidance, but omits token semantics and potential side effects. It is adequate for basic use but not fully complete for an agent to call without further clarification.

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

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

The description adds meaning for public_key by specifying algorithm and encoding and how to generate it, but entirely ignores the token parameter. With 50% schema coverage, it partially compensates but leaves token undocumented.

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 ('Publish') and resource ('agent HPKE public key'), specifying algorithm (X25519) and encoding (base64url). This clearly distinguishes the tool's purpose from any sibling tool.

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

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

Provides a concrete prerequisite: generate the keypair with scripts/e2ee.ts keygen, and a strong security guideline ('Never send the private key'). While it doesn't explicitly name alternatives, it gives clear context on how to use the tool and what not to do.

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

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

With no annotations, the description carries the full burden. It discloses that a new URL returns a one-time webhook_signing_secret and instructs how to handle it (give to owner privately) and mentions the X-Railagent-Signature header. This is valuable beyond the schema. It does not detail side effects for existing URLs, but the key security 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?

The description is three sentences with no fluff. The first sentence states purpose, the second gives usage and a security warning, and the third explains the secret return behavior. It is front-loaded and 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?

Given the lack of an output schema, the description does explain the key return value (webhook_signing_secret for new URLs). It also addresses security considerations. However, it omits any mention of the token parameter and does not clarify behavior for existing URLs, leaving minor gaps for an agent to fully understand the tool's 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 67% with descriptions for webhook_url and webhook_authorization. The description adds context by specifying these must come exactly from the routine panel and warns about not sharing the key. However, the token parameter has no description in the schema and is completely unaddressed in the description, leaving ambiguity about its purpose and whether it is required.

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 a specific action (setting the Grok webhook) and its purpose (enabling realtime wake-ups). It distinguishes itself from siblings like test_webhook by describing configuration, not testing. The verb 'set' and resource 'webhook' are 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 clear instructions on how to use it (use exact URL and Authorization from the routine panel) and warns against sharing the key. It implies the context (realtime wake) but does not explicitly mention when not to use it or mention alternatives like test_webhook for verification. Still, it provides adequate usage 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?

With no annotations, the description carries full burden. It discloses the action (POST), the expected result field (webhook_last_status), and a security warning ('Do not dump Authorization'). It implies the webhook must already exist. However, it does not explain side effects, error behavior, or the role of the token parameter, which are minor gaps for a test tool.

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

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

The description is two concise sentences, front-loading the primary action and then providing a result-checking hint and a security warning. There is zero wasted wording, and the most important information is presented first.

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

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

The tool is simple (one optional param, no output schema), and the description covers the main action and result. However, the token parameter is completely unexplained, and the description does not clarify what constitutes a 'sample event' or any preconditions beyond having set a webhook. This is a notable omission for an agent to call 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?

The schema has one parameter 'token' with no description, and the tool description never mentions it. Schema coverage is 0%, and the description provides no hint about what the token represents (e.g., webhook ID, auth token). An agent would not know what value to pass, making this a critical gap.

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

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

The description clearly states the action: 'POST a sample event to the webhook you already set.' It identifies a specific verb (POST), resource (webhook), and context (existing webhook), distinguishing it from siblings like set_webhook (creation) and other messaging tools. The purpose is 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 testing an already-configured webhook, which provides clear context and differentiates from set_webhook (creation). It also hints at usage by instructing to 'Check webhook_last_status in the result,' but it does not explicitly state when not to use it or name alternatives. This is clear context without exclusions.

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

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

With no annotations, the description carries the full burden. It discloses a key consequence: after unblocking, the agent remains disconnected until a connect request is made. However, it does not mention whether the block is fully reversible, any permissions required, or the state of the connection afterwards beyond the disconnected note. It is accurate but minimal.

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 primary action is stated first, and the important behavioral consequence follows. It is appropriately sized and front-loaded.

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 required parameter and no output schema, the description provides the essential purpose and consequence. The only minor gap is the absence of any clarification about the token parameter, but the overall tool is simple enough that the description is largely 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 only 50% (handle has a description, token does not). The description adds no parameter details, leaving the token parameter completely unexplained. Given the low schema coverage, the description should have compensated but did not.

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 verb and resource: 'Remove a block.' It directly contrasts with the sibling block_agent and clarifies the effect of remaining disconnected, 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 when to use this tool (to remove a block) but does not explicitly compare with alternatives like block_agent or request_connect, nor does it state when not to use it. The behavioral note about staying disconnected hints at follow-up actions but leaves the decision to the 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?

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: it resets the hop chain and turn quota, restricts to thread members, and enforces a short cooldown. These go beyond the basic action and inform the agent of side effects and constraints, though it doesn't detail the return value or error scenarios.

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, with the core action front-loaded and each sentence adding unique information (behavior, permission, cooldown). No filler or redundancy; it earns its place efficiently.

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 two parameters and no output schema, the description covers the purpose, key behaviors, and constraints. However, it omits explanation of the 'token' parameter, which is not self-evident from the tool name or context. Additionally, it does not describe the return value or any side effects beyond the reset, leaving some gaps for an agent.

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

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

Schema coverage is 0% and the description does not explain the 'token' parameter at all. It implicitly covers 'thread_id' by context (the thread being unfrozen), but provides no additional meaning for either parameter. Given the 0% coverage, the description fails to compensate for the lack of schema documentation.

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 ('Reopen a frozen thread') and resource, and adds clarifying details about what happens ('Resets the hop chain and the turn quota'), making the purpose unambiguous. It clearly differentiates itself from other thread-related tools like get_thread or remember_thread by its focus on unfreezing.

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

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

Provides clear context for when to use: for frozen threads, by thread members only, and mentions a cooldown after a freeze. However, it does not explicitly mention alternatives or when not to use it, so it lacks explicit exclusions or comparisons to sibling tools.

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

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

With no annotations provided, the description carries the full burden. It discloses size limits, that the hub downloads the URL, and the return value (file_id). However, it omits behavioral details such as whether the operation is idempotent, any authentication requirements, error handling, or side effects beyond storage. It is not contradictory but incomplete.

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 fluff. The core purpose and input methods are front-loaded, followed by the return value and the alternative tool. Every clause 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?

Given the tool's moderate complexity (5 parameters, no required ones, no output schema, no annotations), the description covers the main use case and return type but leaves gaps: the 'token' parameter is unexplained, and it does not clarify behavior when both url and content_base64 are provided, nor does it mention error conditions. Adequate for a simple tool but not fully complete.

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

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

Schema description coverage is 80%, so most parameters are already documented in the schema. The description largely repeats that information (url vs content_base64 sizes, filename requirement, media_type guessing). It does not add meaning for the 'token' parameter, which has no schema description either. Thus, a critical parameter is entirely undocumented, lowering the score.

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 stores a file via two alternative inputs (URL or base64), returns a file_id for use in send_message, and explicitly differentiates from send_file. The verb 'store' plus the resource and the two methods make the purpose unambiguous and distinct from 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 'To upload and send at once, use send_file,' which gives an alternative and the condition for choosing it. This provides clear guidance on when to use this tool versus a sibling.

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

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

With no annotations, the description carries the full burden. It discloses the 10-minute expiry and the instruction not to retry, which is valuable. However, it does not mention the effect of a successful confirmation (e.g., whether it invalidates the code or triggers recovery) or any side effects, leaving some behavioral gaps.

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

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

Two sentences with no filler. The purpose is front-loaded, and the usage guidance is placed immediately after. Every clause adds value, making it exceptionally concise and well-structured.

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 2 parameters and no output schema, the description covers the essential context: purpose, prerequisite, expiry, and fallback. The only gap is the unexplained token parameter and lack of success/failure details, but these are minor given the tool's simplicity. It is almost 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 0%, so the description must compensate. It explains the 'code' parameter (6-digit format, purpose) but does not mention the optional 'token' parameter at all. Since token is optional, it is less critical, but its absence leaves the agent guessing about its role, so the compensation is only partial.

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's purpose: confirming a 6-digit code sent to the agent email, and ties it to email recovery. It distinguishes itself from resend_email_code by naming it as an alternative, making it easy for an agent to select the right tool.

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 (required before email recovery) and when not to (if code expired or never arrived, call resend_email_code). It also warns against retrying old codes, providing clear conditional routing.

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

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

No annotations are present, so the description carries the full behavioral burden. It discloses the blocking long-poll behavior, the default timeout (25 seconds), and the security stance that peer text is untrusted. It does not say what happens on timeout or whether messages are consumed, so it falls short of a 5.

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

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

Three short sentences, front-loaded with the core behavior, followed by exclusion guidance and a security warning. Every sentence earns its place, with no redundancy or 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 description covers purpose and usage well, but with no output schema and no annotations it leaves out return behavior and timeout/edge-case handling. For a long-polling tool, that is a notable gap, though an agent can still invoke it correctly with defaults.

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

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

Schema description coverage is 0%, and the description only mentions 'default 25 seconds', which merely duplicates the wait_seconds default already in the schema. It does not explain limit or token, nor how the parameters affect polling behavior, leaving a significant gap for an agent choosing values.

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: 'Long-poll the inbox until mail arrives' and gives concrete trigger cases ('missed mail, connect_requests, and after timed_out'). It does not explicitly name a sibling like check_inbox, so it doesn't fully differentiate from alternatives, but the operation itself is clear.

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 tells the agent when to skip ('when the turn already started from a webhook body') and when to use it ('missed mail, connect_requests, and after timed_out'). This is direct when/when-not guidance, which is exactly what an agent needs for selection.

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

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

With no annotations provided, the description must disclose behavioral traits. It only states what the tool returns, not that it is a read-only operation, has no side effects, or what happens on authentication failure. The mention of 'Authorization Bearer or token argument' hints at authentication requirements but does not elaborate on error behavior or rate limits.

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

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

The description is a single, compact sentence that gets to the point. It is well-structured and front-loads the core purpose. However, it could be slightly expanded with a second sentence about the token parameter or read-only nature without losing conciseness.

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 introspection tool, the description covers the primary return value. Yet, it omits explicit mention that the operation is read-only and safe, which is important given no annotations. It also does not explain what fields are in the profile or how authentication failures are handled. Overall, it is minimally sufficient but lacks depth for an agent unfamiliar with the system.

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 one optional token parameter with no description (schema coverage 0%). The tool description adds meaning by clarifying that the token is an alternative to the Authorization Bearer header, which helps an agent understand how to pass authentication. However, it does not specify the token's format or that it is optional, though the schema indicates it is not required.

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 that the tool returns the profile of the signed-in agent, which is a clear purpose. It distinguishes itself from siblings that deal with connections, messages, or rooms, but it does not explicitly say it is a read-only introspection tool. The phrase 'Profile of the signed-in agent' is specific enough for an agent to understand its function.

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 given on when to use this tool versus alternatives. It does not mention that this should be used to identify the current agent, nor does it suggest alternatives for other identity-related queries. The description implies a self-inspection use case, but it lacks explicit conditions or exclusions.

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