DiviMail

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

Annotations already declare non-read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds value beyond them by disclosing the prerequisite challenge step and the returned JWT credential; it does not cover token lifetime or failure modes, so it falls short of 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 tight sentences, front-loaded with the outcome, then the sequencing constraint, then the alternative and return value. Nothing is redundant or 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?

For a three-parameter authentication step with a fully documented schema and stated return value (JWT), the description covers prerequisite, alternative path, and output. No output schema is needed because the return is named.

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

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

Schema coverage is 100% and each property already documents its encoding and meaning (NEAR account ID, base58 public key, base64 Ed25519 signature of the challenge message). The description restates the base64/base58 encodings and adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a concrete verb and outcome: finish signing in with a key or NEAR wallet and obtain the token used for sending, inbox, top-up and pay. It also names the sibling it is not (divimail_login for provision:true accounts), so an agent can pick it out without opening the schema.

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

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

Explicitly positions itself as 'Step 2 of 2' that must be called after divimail_challenge, and names the alternative for provision:true accounts. Both the when-to-use and the when-to-use-something-else conditions are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds something the annotations do not: 'No token needed, just the @divindi.io address', which tells the agent no authentication step is required before calling. It stops short of saying what the response contains (raw amount, formatting, thresholds for 'low'), which keeps it from a 5.

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

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

Three short clauses, each doing work: what it checks, when to call it, and the fallback when the balance is low. The scoping and prerequisite information is front-loaded with 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 single-parameter read tool with full annotation coverage and no output schema, the description covers purpose, prerequisites and the follow-up path. The only gap is the shape of the result and what counts as 'low', which would help an agent decide whether to chain into request_topup.

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

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

Schema description coverage is 100% and there is only one parameter, so the schema already explains the email field. The description reinforces the format constraint ('just the @divindi.io address') but adds no new meaning such as whether other domains are rejected. Baseline 3 applies.

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

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

The description names a specific verb and resource — checking how much USDC a DiviMail address holds — and ties it to a concrete purpose (sending email or paying). An agent can distinguish it from siblings like divimail_pay or divimail_request_topup without opening any schema.

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

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

It gives an explicit trigger ('Call before divimail_send or divimail_pay if unsure') and a named alternative for the low-balance case ('use divimail_request_topup'). Both the when-to-use and the routing decision are stated, not implied.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is largely covered; the description still adds real value by stating that the call returns a challenge message meant to be signed rather than completing authentication. It does not say whether a server-side challenge is created or whether the message expires, which matters given readOnlyHint=false — 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 action and return value, followed by sequencing and then the fallback alternatives. Every clause carries routing information; there is 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 one-parameter, no-output-schema step in a multi-step auth flow, the description supplies the prerequisites, the next call, and the two escape hatches. Nothing an agent needs in order to invoke this correctly is missing.

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

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

With a single parameter at 100% schema description coverage ("Your NEAR account ID (e.g. myagent.near)"), the schema already carries the full parameter meaning. The description adds nothing about accountId — e.g. whether an unregistered account is an error — so the baseline of 3 applies.

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

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

"Start signing in with your own key or NEAR wallet: returns a challenge message to sign. Step 1 of 2." names a specific verb (start sign-in), the resource produced (a challenge message), and its position in a two-step flow. An agent can immediately tell this apart from divimail_authenticate (step 2) and divimail_login (the simpler path).

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 routes between three alternatives with explicit conditions: call this, then divimail_authenticate; use divimail_login if the account was created with provision:true; use divimail_service_token if you have a service secret. That is exactly the when-to-use/when-to-use-something-else guidance that makes a first-step auth tool selectable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond that: an authentication requirement ('Needs a token') and the default page size of 20, which affects result volume. It stops short of describing return fields or how to request further pages, keeping it out of the top band.

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

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

The purpose is front-loaded and the middle sentences form a tight call-ordering chain. The trailing 'Needs a token. Optional limit (default 20).' partly duplicates schema content, which is the only minor waste.

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

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

For a simple read-only list tool with no output schema, the description covers purpose, auth prerequisite, default result count, and next-step tools. Return field shape is unspecified, but the complexity is low enough that this is a small gap rather than a blocking one.

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

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

Schema description coverage is 100% and all three parameters are already documented in the schema, including the email format and the limit default. The description only restates the token requirement and the limit default, adding no syntax or format nuance beyond the structured data, so the baseline 3 applies.

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

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

States a specific verb and resource: 'lists received emails for its @divindi.io address.' It also explicitly contrasts with divimail_sent for outgoing mail, so the agent can distinguish it from siblings without consulting schemas.

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

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

Gives an explicit workflow: 'Call this first to see what arrived, then use divimail_read with a messageId ... and divimail_mark_read when done,' plus a named alternative (divimail_sent) for the opposite use case. This is textbook when-to-use and when-not guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds what those annotations cannot: the business rationale (avoid double handling) and an auth requirement ("Needs a token"). Minor tension exists in that the schema marks token optional while the description says it is needed, but this is not an annotation contradiction.

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

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

Three short sentences, front-loaded with purpose, then usage, then prerequisite. No filler and nothing that repeats the schema verbatim.

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

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

For a three-parameter mutation tool with full schema coverage and no output schema, the description covers purpose, sequencing, and auth prerequisites, which is enough to invoke it correctly. It does not say what the response looks like or whether the read state is reflected elsewhere, a small residual gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real meaning on top by specifying that messageId must be the same one used in the preceding divimail_read or divimail_inbox call, disambiguating where the identifier should come from.

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 ("Mark an email ... as read") plus the scope constraint ("in your agent's inbox"), and the rationale "so it is not handled twice" makes the state change unambiguous. It is clearly distinguishable from siblings like divimail_read and divimail_inbox, which only retrieve.

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?

"Use after divimail_read (or divimail_inbox) with the same messageId" gives explicit ordering and names the preceding sibling calls, which is exactly the guidance an agent needs for sequencing. It stops short of stating when not to call it (e.g., already-read messages), so it is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful context beyond annotations: a token is required, and reading does not itself mark the email read. It could say more about authentication failure behavior, but it is strong for a read 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 compact sentences with no wasted wording. It front-loads the action, then gives sequencing and follow-up guidance.

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

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

For a simple read-one-email tool with full schema coverage and annotations covering safety, the description is complete. It explains prerequisites, sequencing, and the optional mark-read follow-up, so nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so all three parameters, including email, token, and messageId, are already documented in the schema. The description reinforces that messageId comes from divimail_inbox and that a token is needed, but adds no syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: open and read one email in full, including body and details, from the agent's mailbox. It clearly distinguishes this from divimail_inbox, which lists messages, so an agent can identify the right tool without opening the schema.

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

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

It explicitly says to call this after divimail_inbox using a messageId from that list. It also names divimail_mark_read as the follow-up for marking read, giving clear sequencing and 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?

Goes well past the annotations by disclosing that provision and publicKey both return an apiKey shown ONCE and must be saved, and that only the public key is stored (no private key held server-side). This reinforces idempotentHint=false with 'call this once'. It stops short of describing failure behavior, such as what happens if the alias is already taken.

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

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

Four short sentences, front-loaded with the purpose, then sequencing, then the parameter choice rule, then the one-time secret warning. No filler and the most actionable constraint (save the apiKey) closes the description.

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

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

With no output schema, the description correctly compensates by stating what provision/publicKey return. Sequencing to the auth siblings is covered. What is missing is error/edge handling — alias collisions, existing registrations, or what to do if the apiKey is lost — which matters for a non-idempotent creation call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot express: the three identity parameters are mutually exclusive modes, and provision/publicKey carry a one-time apiKey return consequence. That mutual-exclusivity rule is genuine added value.

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

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

States a specific verb and resource — 'Give an AI agent its own @divindi.io email address so it can send and receive email' — which unambiguously separates this creation step from the sibling auth tools (divimail_login, divimail_challenge, divimail_authenticate) and mail 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?

Explicitly says to call this once, then names the exact follow-up path (divimail_login, or divimail_challenge + divimail_authenticate) to obtain a token. It also states the mutually exclusive selection rule across provision/publicKey/nearAccountId with 'Use exactly one of', and ranks them ('provision:true (easiest)').

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

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

Annotations already declare this is a non-read-only, open-world, non-idempotent but non-destructive write. The description adds genuinely new context beyond that: a $0.01 USDC per-email cost, the authentication dependency chain, a top-up escape hatch on low balance, and the sender-address constraint. It does not disclose failure behavior (what happens if payment or delivery fails, whether a failed send is charged), which is the main remaining gap.

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

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

Four short sentences, front-loaded with the core action, then auth, then cost, then body options. Every sentence supplies actionable information and none is redundant filler.

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

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

For an 8-parameter, open-world send operation with full schema coverage and annotations, the description covers action, auth, cost, and top-up path. The notable omission is what the call returns (message id, status) since there is no output schema to fall back on.

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

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

Schema description coverage is 100%, so every parameter including cc, bcc, html, and token is already documented in the schema. The description's mention of 'plain text, optional HTML, CC and BCC' restates that coverage rather than adding format or constraint detail. Baseline 3 is appropriate when the schema carries the 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?

States a specific verb and resource ('Send an email') plus the exact scope: from the agent's @divindi.io address to any email, human or agent. The nature of the tool is unmistakable against siblings like divimail_inbox, divimail_read, and divimail_sent, which are all read-side operations.

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

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

Gives a concrete prerequisite ('Needs a token from divimail_login (or authenticate/service_token)') and routes to divimail_balance and divimail_request_topup when funds are low. It does not state when-not to use it (e.g., don't use for replies inside a thread, use divimail_read first), so it stops short of full 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?

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds scoping (only its own @divindi.io address) and the default limit of 20, but says nothing about ordering, pagination beyond the limit, or whether messages are ever truncated. Adequate but thin beyond what structured fields give.

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

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

Four short front-loaded sentences with no filler; purpose, use cases, alternative and prerequisites each appear once. Slight redundancy in restating the limit default already present in the schema keeps it from a 5.

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 small read-only list tool with no output schema, this covers what it returns (sent messages), whose mailbox (the agent's own address), the auth prerequisite, and the sibling to use for the other direction. Return shape and ordering are the only real omissions.

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

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

Schema coverage is 100%, so the schema already documents email, limit and token fully. The description's 'Optional limit (default 20)' simply repeats the schema field description, adding no new meaning such as max values or ordering 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?

States a specific verb and resource ('lists sent messages for its @divindi.io address') and immediately disambiguates from the closest sibling: 'For received mail use divimail_inbox.' An agent can pick this over divimail_inbox or divimail_send without reading any schema.

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

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

Gives two concrete use cases ('confirm a divimail_send went out' or 'review history') and names the alternative tool for the opposite direction. Missing only an explicit exclusion such as when limit should be raised or when this is pointless to call.

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