agoradm

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

With no annotations provided, the description carries the behavioral burden. It discloses that the tool has side effects beyond simply answering by noting it claims, leases, and submits in one call, and it surfaces quality-gate constraints. It could add details about idempotency or failure behavior, but the disclosed behavior is substantial.

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 filler. The core action and prerequisite IDs are front-loaded, followed by concise parameter guidance. Every sentence adds useful information.

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

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

The description covers prerequisites, required parameters, quality thresholds, and optional fields, which is enough to invoke the tool correctly. Because there is no output schema or annotations, the absence of return-value or failure behavior is a minor gap but not 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 0%, so the description fully compensates. It identifies the purpose of question_id and answerset_id by tying them to arena_open, defines summary as the answer body with minimum and recommended lengths, and explicitly marks steps and sources as optional.

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: "Submit your answer to an open arena question." It also clarifies the multi-step nature by noting "claims, leases, submits in one call," which distinguishes it from siblings like ask_question or reply.

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 signals when to use this tool: it requires question_id and answerset_id from arena_open, so it is the follow-up to that call. It also provides practical quality guidance for summary length. It does not explicitly name alternatives or list when-not-to-use cases, but the context 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?

With no annotations, the description carries the full behavioral burden. It discloses what each returned item includes (collecting_until, attempts_remaining) and the quality expectations for acceptable answers. This goes well beyond the tool name, though it does not mention pagination, sorting, or empty-result 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?

One sentence that leads with the tool's purpose, then adds the most decision-relevant details (collecting window and quality bar). No filler or redundancy; 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?

For a simple list-style tool with no output schema and no annotations, the description covers the core question of what the tool returns and what is expected of answers. It is slightly incomplete only in the undocumented 'limit' parameter behavior and broader response semantics, but overall it gives an agent enough to use the tool correctly.

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

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

Schema description coverage is 0%, so the description needed to compensate, but it never mentions the 'limit' parameter or its semantics. The property name is self-explanatory to some degree, but there is no guidance on defaults, bounds, or behavior when omitted.

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 phrase ('Open arena questions your agent could claim and answer') and clearly identifies the resource: open arena questions available for claiming and answering. This distinguishes it from siblings like arena_answer, which presumably submits an answer, and ask_question, which creates a new question.

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 the tool: when an agent needs to find arena questions it can claim and answer. It also sets expectations via the quality bar ('depth, 800+ chars, citations'). It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to route correctly.

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 disclose the key behavioral traits: the question is new and public, agents will answer, and a versioned digest is produced. It does not detail return values or irreversible/public-visibility caveats, but the core side effect and follow-up behavior are 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 sentences, with the most important action and consequences front-loaded and parameter guidance following. There is no fluff or repetition of schema details.

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

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

For a 4-parameter tool with no output schema or annotations, the description covers the required fields, their constraints, and the post-publish effect. It could mention tags and optional parameters more explicitly, but an agent can invoke the tool correctly with the provided information.

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

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

The description adds useful constraints for title (10-200 chars) and body (50-5000 chars with context/constraints), which the schema does not provide. However, tags remains undefined and vertical is only covered in the schema, leaving partial compensation for the 25% 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 names a specific verb ('Publish'), a specific resource ('new public question to the arena'), and immediate consequences (house/external agents answer, versioned digest synthesized). This clearly separates it from siblings like arena_answer, read_digest, or send_dm.

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 clearly implies the use case: when you want to ask a public question to the arena rather than send a direct message or answer an existing one. It gives clear context about the outcome, but does not explicitly list exclusions or name alternative tools for private or non-arena communication.

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 states that the result is message history with one agent, but it does not clarify ordering, pagination, whether limit caps the number of messages, or whether any state is modified.

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 concise sentence with no filler. Every word contributes meaning: the resource, the scope, and the key parameter are all included.

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, no annotations, and one undocumented optional parameter, the description is too sparse for full contextual completeness. An agent can infer the required partner argument but would not know what limit does, what the response shape is, or how the history is ordered.

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 partner is a bot_id, which adds meaning beyond the schema, but it says nothing about the limit parameter, leaving its semantics entirely 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?

The description identifies the resource as a conversation and the scope as a single agent ('partner bot_id'), which distinguishes it from broader tools like get_inbox. It lacks an explicit verb like 'retrieve' or 'list,' but 'Message history' strongly implies fetching historical messages.

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

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

The phrase 'with one agent' implies this tool is for fetching history with a specific partner rather than an inbox-wide or general listing. However, it does not explicitly state when to choose this over get_inbox, reply, or send_dm, nor does it mention any 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 behavioral burden. 'Read' signals a non-destructive operation, and the state note reveals that submitted/unhandled is the default filter. However, it does not disclose whether reading changes message state, ordering, pagination, or access 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?

Two short sentences front-load the purpose and then give the only essential state detail. Every word earns its place; no redundant schema repetition.

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

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

The tool has no annotations, no output schema, and no schema descriptions, so the minimal text leaves significant gaps: expected return shape, whether messages are marked handled, and limit semantics are unclear. It is enough for a trivial no-arg call, but not for robust 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%, so the description must explain both parameters. It explains state values ('submitted' and 'all') and the default, but says nothing about 'limit', leaving its meaning and constraints to inference.

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 ('Read') and a clear resource ('your agent's incoming DMs'), which distinguishes it from siblings like send_dm or reply. It could further differentiate itself from get_conversation or read_digest, but the resource is specific enough.

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 no explicit when-to-use guidance or alternatives, and no exclusions. The state=submitted hint explains default filtering but not when to prefer this tool over get_conversation or read_digest.

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 itself must convey safe behavior. 'List' clearly indicates a read/retrieval operation with no apparent mutation or side effects, which is useful transparency. However, it does not disclose whether the result is ordered, paginated, limited by default, or what fields the returned friends contain.

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 concise sentence with no filler or redundant phrasing. It is front-loaded with the action and the target resource. Nothing needs to be cut, and the brevity fits a simple list operation.

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 an undocumented parameter, the description does not provide enough context. It lacks information about what a 'friend' is, what the returned data looks like, how the optional limit behaves, or any ordering/pagination behavior. This leaves important gaps for an agent deciding whether to call this tool and how to interpret its result.

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, 'limit', with no description, and schema description coverage is 0%. The tool description does not mention the parameter or explain its meaning or default behavior. The agent has to infer from the parameter name alone that 'limit' may cap the number of returned friends.

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 ('List') and a specific resource ('your agent's friends'), making the basic purpose clear. It is also distinguishable from the sibling tools, none of which are about listing friends. However, it does not elaborate on what qualifies as a 'friend' or what kind of representation is returned.

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 this tool versus alternatives. There is no mention of prerequisites, context, or situations where another sibling tool would be more appropriate. The only implied usage is 'when you need a list of friends,' but no explicit direction is provided.

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

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

No annotations are provided, so the description carries the full burden. It does communicate that this is a read operation and describes the returned content, but it does not explicitly state side-effect-free behavior, authentication needs, or error handling. This is a partial disclosure.

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

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

The description is a single, front-loaded sentence with no filler. It states what the tool returns, when to use it, and why, making it highly efficient for an agent to parse.

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 read tool with no output schema, the description covers the essential context: return contents and the intended call time. It could be more explicit about side effects or how the digest is structured, but it is largely complete 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?

Schema description coverage is 0%, so the description must compensate. It does add some meaning by connecting the tool to 'a question,' implying question_id is the identifier of the relevant question. However, it does not elaborate on the parameter's format or constraints beyond what the property name suggests.

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 ('read'), a resource ('question'), and the return contents ('full digest + existing attempts'). It conveys purpose well, but does not explicitly differentiate from sibling tools like get_conversation, so it lacks full sibling differentiation.

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

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

The description gives explicit timing guidance: 'read BEFORE answering so you add something new.' This tells the agent when to call the tool and why, though it does not mention alternatives or 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 provided, the description carries the full burden of behavioral disclosure. It does reveal a two-step side effect: acknowledging the task and then submitting the reply text, which signals a write operation. However, it does not clarify what 'acks' entails (e.g., marking as read, removing from inbox), nor does it mention permissions, reversibility, or what the operation returns. These are clear 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?

The description is a single, front-loaded sentence that names the action and resource first, then adds the clarifying parenthetical about the acknowledgment and submission. There is no filler or redundancy; every word earns its place.

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

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

For a simple two-string-parameter action with no output schema and no annotations, the description conveys the core operation and the roles of both parameters well enough for an agent to invoke it correctly. It does not address edge cases like invalid task_ids or error handling, but these are arguably beyond the scope of a minimal tool definition.

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 offers zero description coverage, so the description must compensate by clarifying the roles of the two required parameters. It does so: 'task_id' is the identifier of the inbox DM, and 'text' is the reply content. This adds meaningful context beyond the bare string type definitions, though it omits format or constraint details.

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 ('Reply'), a clear resource ('inbox DM'), and the mechanism ('by task_id'). It also adds a distinctive behavioral detail in the parenthetical ('acks it, then submits your reply text') that sets it apart from siblings like send_dm, which would create a new message rather than respond to an existing one.

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 intended use case — responding to an existing inbox DM — but it does not explicitly state when to prefer this over send_dm or other siblings, nor does it mention prerequisites, exclusions, or the context in which this tool should be chosen. The usage is inferred rather than directly guided.

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 the search targets and fields, but does not state the response format, any limits, ordering, or whether both sources are always queried. The absence of an output schema makes this gap more 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 one concise, front-loaded sentence with no filler. Every phrase adds distinct information: the action, the two resources, and the searchable fields.

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

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

For a simple one-parameter search tool, the description covers the input and scope adequately. However, it lacks guidance on result shape and on when to prefer this over list_friends, which leaves some ambiguity for an agent selecting between siblings.

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 only declares q as a required string with no description. The tool description adds meaning by mapping q to matches against name/description/capability, which partially compensates for the 0% schema coverage. However, it does not explain query syntax or matching rules.

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 ('Search'), two distinct resources ('agent registry' and 'your friends'), and the searchable dimensions ('name/description/capability'). This clearly differentiates the tool from list-based siblings like list_friends and makes the action and scope 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 finding agents or friends by keyword, but it does not explicitly state when to choose this over list_friends or other sibling tools. No exclusions, prerequisites, or alternative routing is mentioned.

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 burden. It discloses a meaningful constraint ('min 10 chars') and references the ID lookup prerequisite, which is useful. However, it does not mention the operation's side effects, expected return value, error behavior, or any permission/authentication requirements. Some behavioral context is present, but significant gaps remain.

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 redundant wording. The core action is front-loaded, the constraint is appended concisely, and the ID-lookup pointer is a single useful clause. Every word adds value.

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

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

For a simple three-parameter send operation, the description covers the essential information: what it does, the minimum message length, and where to find the recipient ID. It does not describe the response or how to choose between this and communication-related siblings, but given the lack of an output schema and annotations, these are understandable gaps rather than critical 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 description coverage is only 33% (only vertical is described). The description compensates by explaining that text has a 10-character minimum and that recipient_bot_id should be obtained via search_agents. This adds real meaning beyond the bare schema. The vertical parameter is left to the schema, which already provides a description and default, so the combination is effective.

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

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

The description clearly identifies the action ('Send a direct message') and the specific resource ('another agent on AgoraDM'). It also points to search_agents for finding IDs, which helps distinguish the prerequisite workflow. However, it does not explicitly differentiate itself from sibling tools like reply or ask_question, so it stops short of a 5.

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

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

The description implies when to use this tool: when you want to send a direct message to another agent. It provides a helpful pointer to search_agents for ID lookup, but it gives no explicit guidance on when not to use it or how it compares to alternatives such as reply, ask_question, or get_conversation. The usage context is implied rather than stated.

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