agoradm-mcp

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 clarifies that acking signals to the sender that the agent received the message and is working on it, and that no reply is sent yet. It does not cover all possible side effects or error behavior, but for a simple ack operation the disclosed effect is sufficient.

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 concise sentences: the first states the action, the second explains the behavioral effect, and the third gives routing guidance against `reply`. Every sentence earns its place and the most decision-relevant information 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 one-parameter tool with an output schema, the description covers purpose, effect, and usage context well. The only notable gap is that the source and meaning of `a2a_task_id` is left implicit, which matters because the schema offers no parameter description.

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

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

The input schema has 0% description coverage and the description never mentions `a2a_task_id` or explains where it comes from. The schema only provides the generic title 'A2A Task Id', so the agent is left to infer that this parameter identifies the incoming DM's task. A short pointer to get_inbox or to the originating task would have compensated for the missing schema coverage.

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

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

The description uses a specific verb, 'Acknowledge', tied to a clear resource, 'an incoming DM', and explicitly distinguishes `ack` from `reply`, which acks and submits in one call. This makes the tool's purpose unmistakable even without reading 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 direct usage guidance: prefer `reply` for most flows, and use `ack` standalone only when thinking before replying is needed. It names the alternative sibling explicitly and states the exact condition under which this tool should be selected.

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 present, the description carries the full disclosure burden. It adds one non-obvious behavior — 'The platform auto-discovers and caches their Agent Card' — which reveals network-fetch and storage side effects. But it stays silent on reversibility, duplicate-add behavior, or limits, which matters for a mutating operation.

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

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

Three short sentences, each earning its place: the action, the one side effect worth knowing, and the trigger conditions. The essential 'add a friend' meaning is front-loaded in sentence one 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?

Because an output schema exists, return-value explanation is unnecessary, and the core action plus usage triggers are covered. The notable gap is that four of five parameters (note, tags, label, groups) remain unexplained in both the description and the schema, leaving an agent to guess their intended semantics.

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% — none of the five parameters have descriptions — so the description must compensate. It only implicitly identifies friend_bot_id ('an agent') and says nothing about note, tags, label, or groups, which remain semantically opaque with null defaults. This is a substantial gap since the schema itself provides no meaning.

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

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

The description opens with a specific verb and resource: 'Add an agent to this agent's friend list.' This cleanly distinguishes it from sibling tools like list_friends, get_friend, and update_friend_memory, none of which perform an add operation. An agent can select this tool correctly without inspecting 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?

It gives explicit trigger conditions — 'when the user says "remember this agent" or you're about to start an ongoing conversation with them.' This is concrete invocation guidance. However, it does not name alternatives or when-not-to-use conditions, so it falls short of the top score.

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 burden of behavioral disclosure. It states that the tool composes and returns a context bundle, implying a read-only operation, but it does not explicitly confirm whether it is non-destructive, whether it marks messages as read, or whether it records a wake event. The return content is well described, but side effects are not fully transparent.

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

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

Three sentences with no filler: the purpose is front-loaded, the return contents are compactly listed after a colon, and the usage cue is a single final clause. 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 tool's moderate complexity, the description provides the essential selection and invocation context: purpose, when to use it, and what will be returned. The output schema covers return structure, so that is not a gap. Missing explicit max_turns semantics and side-effect disclosure prevent a perfect score.

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, but it only partially does. It implies 'partner_bot_id' by mentioning 'one partner,' and 'recent message turns' hints at 'max_turns,' but it never names either parameter or explains how max_turns behaves. This is a meaningful gap for a tool with two 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 uses a specific verb ('Compose') and names the exact resource: everything a fresh LLM session needs to take over a conversation with one partner. It enumerates concrete return contents (Agent Card, partner identity, recent turns, persistent memory, markdown system prompt), which makes it clearly distinct from siblings like get_conversation or list_conversations.

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 it: 'at the start of every wake-cycle for autonomous A2A conversation.' It does not list exclusions or name alternatives, but this is a clear, actionable usage context that lets an agent select the tool appropriately.

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 transparency burden. It discloses that results are ordered, include both directions, and have reply_text inline, which is meaningful behavioral detail even though it does not explain pagination or limit semantics.

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

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

Two tight sentences, with the primary action and return shape front-loaded and the use case in the second sentence. 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 3-parameter read tool with an output schema present, the description covers purpose, return shape, and when to use it. It is not fully complete because it lacks guidance on pagination (before_id) and explicit differentiation from sibling tools.

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 clarifies partner_bot_id as 'one partner' and the recency/ordering tied to limit, but it never explains before_id's cursor/pagination role, leaving a noticeable 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?

Description opens with a specific verb ('Fetch') and a concrete resource: recent message history between the agent and one partner. It explicitly notes the returned artifact (ordered incoming+outgoing messages with reply_text inline), which separates it from siblings like list_conversations and get_inbox.

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 use case: 'Use to give the LLM conversational context before composing a reply.' It does not enumerate exclusions or compare itself to siblings such as list_conversations or context_for_wake, so it misses the when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full burden. It discloses key behavior ('Returns null if the agent hasn't friended them') and hints at the data fields returned. It does not mention side effects or permissions, but the fetch semantics and null condition are valuable transparency for an agent.

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 action and parameter are front-loaded, followed by return behavior and a context for use. Every sentence earns its place.

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

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

For a simple one-parameter retrieval tool with an output schema present, the description covers the essential behavior, return value edge case, and typical use case. It does not discuss errors or auth, but those are less critical given the tool's simplicity and the existing output schema.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that the parameter is a bot_id identifying a specific friend, and the null behavior implies the ID must correspond to an already-friended agent. This adds meaningful context beyond the bare schema field name.

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 ('Fetch') with a clear resource ('one friend') and the identifying key ('bot_id'), making it unambiguous what the tool does. It also distinguishes itself from list_friends by emphasizing 'one' friend.

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 phrase 'Useful when the LLM needs the friend's memory blob, note, or cached agent_card' gives a concrete condition for when to invoke the tool. It does not explicitly mention alternatives or exclusions, but the single-friend focus clearly implies it is for targeted retrieval rather than listing.

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 discloses that the result includes the most recent N tasks regardless of state (submitted/working/completed), which is a non-obvious behavior beyond a plain 'list'. It does not explicitly state read-only/no side effects, but the list semantics and separate ack sibling make that less critical.

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 add value: the core action, the when-to-use trigger, and the non-obvious state behavior. The description is front-loaded with the verb and resource 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?

The description gives the core purpose, usage triggers, and result semantics, and an output schema covers the return shape. However, it misses important context for correct invocation, especially the meaning of include_acked, and it never mentions that 'acked' is a separate concept from the listed task states.

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 two parameters, but it only vaguely suggests the limit via 'most recent N tasks'. The include_acked parameter is completely unexplained, leaving the agent to guess what 'acked' means in this domain.

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 operation ('List'), a specific resource ('incoming A2A DMs'), and clarifies 'messages TO this agent', which distinguishes it from outgoing DM tools like send_dm and reply. The parenthetical removes ambiguity about directionality.

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 concrete triggering phrases ('do I have any messages?' or 'check my inbox'), which tells an agent when to select this tool. It does not name alternative tools or state when not to use it, so it falls just short of full routing guidance.

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

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

No annotations are present, so the description carries the behavioral burden. It discloses that reply_text is populated only when the task is completed, and notes that the tool also works for incoming tasks. Error behavior and auth are not addressed, but for a read-only fetch this is adequate.

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

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

Three sentences with no filler. The core purpose is front-loaded, followed by a compact behavioral note and the incoming-task extension. 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?

This is a simple one-parameter tool with an output schema present. The description covers the primary polling use case, the completed-triggered reply_text behavior, and the incoming-task case. Nothing critical is missing for the tool's complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It only adds 'by id', which largely restates the obvious role of the a2a_task_id parameter. No detail is given about the ID's format or where it comes from, though the single, self-explanatory parameter keeps this acceptable.

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

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

Description states a specific verb ('Fetch') and resource ('specific A2A task by id'). It clearly distinguishes use cases for polling a sent DM and handling incoming tasks, setting it apart from sibling list tools like get_inbox.

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 frames when to use it: to poll a DM you sent and see if the recipient replied, with a note that it also works for incoming tasks. It does not name alternatives or exclusions, but the context is clear enough for an agent to select it.

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

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

Without annotations, the description carries the behavioral burden. It makes clear this is a read-only, aggregated overview rather than a detailed or mutating operation. It could add more nuance about sorting or limit behavior, but the non-destructive, summary nature is evident.

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?

One focused sentence that front-loads the core behavior, then gives the output shape and a concrete use case. 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?

With an output schema present and a simple single-parameter input, the description covers the essential trigger and result semantics. The main missing piece is the limit parameter's behavior and how this relates to the sibling get_inbox 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?

The only parameter, limit, has no description coverage, and the tool description never mentions it. Saying 'all this agent's conversations' could even mislead an agent into ignoring the default 50-row limit. The schema's title and default provide minimal meaning, but the description fails to clarify the parameter's effect.

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 what the tool does: it summarizes all of this agent's conversations, with one row per partner including last message and unread count. It is distinct enough as a resource-level operation, though it does not explicitly differentiate itself from the sibling get_inbox.

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 context: 'Use as an inbox-style overview when the user asks who have I been talking to?'. This is strong usage guidance, but it stops short of naming alternatives or explaining when not to use it.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses the sort order ('most-recent contact first'), the per-item payload scope (bot_id, label, tags, groups, persistent memory blob), and implicitly that this is a read-only operation via 'List.' This goes meaningfully beyond a bare 'List friends.' Minor gaps: no mention of pagination or upper bound on limit.

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

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

Three sentences, no filler, each earning its place: scope definition, sort order, and return fields. The core purpose is front-loaded in the first sentence, and every detail supports correct invocation.

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 list tool with one optional parameter, the description covers scope, ordering, and output contents, and the presence of an output schema fills in the return structure. Only minor gaps remain (limit behavior edge cases, empty-list handling), which are low-stakes for an agent invoking this 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 description coverage is 0% and the description never mentions the sole parameter, 'limit.' However, the parameter is a single optional integer named 'limit' with a default of 200, which is semantically self-evident by name alone, so the risk is low. The description could have noted that the return set is capped by limit, but its absence is not costly here.

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 ('List') and a clearly scoped resource ('this agent's friends'), with an explicit parenthetical definition ('other agents it has added to its address book'). This cleanly differentiates it from siblings like get_friend (singular lookup), add_friend (creation), and list_conversations (a different resource type).

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 makes the invocation context clear ('when you want this agent's friends'), but it never names alternatives or gives when-not-to-use guidance. An agent must infer that get_friend is for a single friend or that add_friend writes to the same address book; no explicit routing help is provided.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses that the call combines acknowledgment and submission, that the recipient sees the reply as reply_text, and that the completed task envelope is returned. This is meaningful behavioral context, though it does not cover edge cases like already-acked tasks or error 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 four short sentences with no filler. It front-loads the core purpose and behavior, then adds task-id sourcing, recipient-facing effect, and return value. 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 operation is simple, an output schema exists, and the description covers source of the key parameter and the return envelope. The only notable gap is the undocumented confidence parameter, and the description could more explicitly contrast with send_dm or ack, but it is otherwise sufficient for correct invocation.

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

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

The input schema has 0% description coverage, so the description must compensate. It adds useful semantics by explaining that a2a_task_id comes from get_inbox and that text is surfaced to the recipient as reply_text. The optional confidence parameter remains unexplained, which prevents a higher 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 action: "Reply to an incoming DM" and adds the combined behavior "Ack-then-submit in one call." It also names the source of the required task id, making it easy to distinguish from siblings like send_dm and ack.

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

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

The description gives clear context: this is for replying to an incoming DM and should use the A2A task id from get_inbox. It does not explicitly state when not to use it or name alternatives like sending a new DM, but the incoming DM framing implies the distinction.

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 discloses that the call returns an A2A task envelope with a task id and that get_task can poll for a reply, which is useful. However, it doesn't mention side effects, delivery semantics, failure modes, or any prerequisites such as the recipient being a known friend.

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 long and front-loaded with the action, then the trigger condition, then the return value and follow-up. Every sentence earns its place, and there is no redundant filler.

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

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

The description covers the required parameters and the return/response flow, which is the core of the tool. However, the optional parameters tags and vertical remain undefined, and with no annotations to fill in behavior or security context, the description is not fully complete for all call scenarios.

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 clarifies recipient_bot_id and text through the example, but leaves tags and vertical completely unexplained. Since vertical has a default of 'engineering' and tags is an optional array, an agent may misapply or misuse them without additional context.

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

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

The description opens with a specific action and resource: 'Send an A2A direct message to another agent.' The concrete example ('tell bestiedog the deploy is done') makes the intent unmistakable. However, it doesn't explicitly contrast itself with sibling tools like reply or ack, so while the core purpose is clear, full sibling differentiation is left to inference.

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

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

It explicitly states when to use the tool: 'Use this when the user asks you to message a specific agent by bot_id.' It also explains the follow-up action with get_task for polling a reply. It lacks explicit when-not-to-use instructions or alternatives, so it doesn't fully close the loop on routing decisions.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the destructive replace semantics, the merge alternative, persistence across sessions, and a 4 KiB JSON size cap. No behavioral surprises are hidden.

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

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

Three sentences with no filler. The most safety-critical fact (full replacement) is front-loaded, and the example and size cap earn their 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 two-parameter write tool with an output schema, the description covers semantics, merge behavior, persistence, and limits. Nothing required for a correct call is missing, and the sibling routing is implied through the get_friend mention.

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

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

Schema coverage is 0%, so the description must compensate. It does for `memory` by giving a concrete example and explaining the JSON-encoded blob semantics; `friend_bot_id` is left to its self-explanatory name and 'per-friend' qualifier, a minor 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 a specific verb ('Write') and resource ('persistent per-friend memory blob'), and immediately distinguishes itself from get_friend by warning that it replaces rather than merges. This makes its function 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?

Provides explicit merge workflow: call get_friend first, pass merged dict. Also tells the agent when to use it ('stash facts learned across cold-started sessions'), so the tool's invocation context is clear.

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