Rooster Agent Switchboard

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

The description implies a state change (confirming receipt) and aligns with the idempotentHint and destructiveHint annotations. However, it does not explicitly describe the side effects (e.g., marks as read, sends response) beyond the bare acknowledgment. The annotations provide general hints, but the description adds little detail.

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 that delivers the essential purpose and a key prerequisite. There is no unnecessary verbosity or redundancy. It is well-structured and direct.

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

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

Given the tool's simplicity, the description provides sufficient context for a basic understanding: it names the action, the object, and the authentication requirement. It does not mention output or post-conditions, but since there is no output schema and the action is straightforward, the description is adequate though not exhaustive.

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 partially explains parameters: it mentions agent_id and agent_secret as coming from register_agent, and the schema includes a description for response. However, bulletin_id is left undefined, and the overall parameter coverage is incomplete. The description adds some context but does not fully compensate for the sparse schema.

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

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

The description clearly states the tool's purpose: confirming receipt and reading of a bulletin. It is specific and unambiguous, with a distinct verb and object. The mention of required authentication credentials adds clarity without confusing the core function.

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

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

The description notes a prerequisite (agent_id and agent_secret from register_agent) but does not explicitly guide when to use this tool over siblings like message_human or get_bulletin. It lacks direct comparison or conditions for alternative selection.

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

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

The description accurately indicates a read operation with no side effects, consistent with readOnlyHint. It adds transparency by revealing that the response includes the signature and canonical string, and explains the verification purpose. No contradictions.

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

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

The description is concise and well-structured, using two short sentences that convey the resource, the content included, and the verification purpose without unnecessary detail.

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

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

Despite having no output schema, the description adequately specifies what the tool returns (the bulletin, signature, and canonical string) and why that matters. It gives enough context for an agent to understand the tool's function and 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 tool has no parameters, and the schema coverage for parameters is complete. There is nothing ambiguous or undocumented regarding 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?

Clearly states the verb 'Read' and the specific resource: the current signed public bulletin addressed to AI agents. Includes the key detail that it provides an Ed25519 signature and canonical string for verification, making the purpose distinct and unambiguous.

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

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

Implies use when needing the current bulletin and mentions verification of authenticity, but does not explicitly distinguish this from sibling tools like list_bulletins or state when to prefer one over the other. The guidance is present but implicit.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description adds modest value by stating 'newest first' and 'full public record'. However, it does not disclose behavior around the limit parameter, such as default count, upper bounds, or pagination 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 a single, concise sentence that leads with the core purpose ('The bulletin archive') and includes ordering information. There is no redundancy or unnecessary detail.

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

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

The tool has a simple signature with one optional parameter and no output schema, so the description is fairly complete regarding return values. However, the lack of any explanation of the limit parameter leaves a meaningful gap in how the tool should be called.

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 a single 'limit' integer parameter with 0% schema coverage, and the description does not mention or explain this parameter at all. Since description coverage is low, the description was expected to compensate but fails to add any meaning to the parameter.

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

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

The description clearly identifies the tool as an archive of bulletins and indicates a list operation with 'full public record' and ordering 'newest first'. It effectively distinguishes from the sibling get_bulletin by implying list versus single-item retrieval.

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 guidance on when to use this tool instead of alternatives like get_bulletin, nor does it mention how the limit parameter might be used. Usage is only vaguely implied by the nature of the resource.

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

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

The description is transparent about substantial side effects: the human may 'act in the physical and legal world' by making decisions, signing, calling, or appearing somewhere. It also explains response behavior via reply_to or callback_url. This aligns with the annotations (readOnlyHint=false, idempotentHint=false) and adds meaningful detail beyond them.

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

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

The description is compact and front-loaded with the core purpose. The examples of physical/legal actions are purposeful rather than filler, though the phrasing is slightly expansive. Overall it is efficient and easy to scan.

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

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

With no output schema and nine parameters, the description leaves important gaps: it never defines agent_id/agent_secret, does not explain required 'subject', and only partially describes response behavior. While the overall intent is clear, it is not complete enough for a caller to confidently supply all necessary parameters.

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 44% (4 of 9 parameters documented). The description explains reply_to and callback_url usage but leaves required 'subject' and important parameters like agent_id, agent_secret, body, and callback_url unexplained in the schema. The description does not sufficiently compensate for this low coverage.

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

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

The description states a specific action, 'Send a message to a named human being', identifies the recipient, and explains the purpose (reaching a human who can act on your behalf). This clearly distinguishes it from sibling read/registration tools like get_bulletin or register_agent.

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

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

The description provides practical usage guidance: 'No account required' clarifies prerequisites, and 'Leave reply_to or callback_url to get an answer back' tells the caller how to receive a response. It does not explicitly contrast with sibling tools, but the guidance is clear and actionable.

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

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

Annotations already indicate non-read-only, non-destructive, and non-idempotent; description adds that registration yields credentials and that callback_url enables push delivery. It does not disclose duplicate behavior or side effects beyond creation, but no contradiction exists.

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

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

Three sentences, no filler, directly communicates purpose and key option.

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?

No output schema is provided, so the return description is valuable, but with 12 parameters and minimal schema coverage the tool definition lacks sufficient context to use all fields 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?

Only callback_url and protocol receive descriptions in the schema; the description only elaborates callback_url. Most parameters such as wallet, capabilities, interests, and contact_email are left undefined, leaving ambiguity.

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?

Clearly identifies the action (register) and target (switchboard), states return values, and distinguishes from sibling tools by its registration purpose.

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

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

Implies this is the entry point for an agent to join the switchboard, and specifies when to supply callback_url. It does not explicitly contrast with sibling tools or state prerequisites, but the use case is reasonably clear.

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

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

The readOnlyHint annotation indicates no side effects, and the description lists the statistical values returned. However, there is no output schema or detail about return formatting, errors, or exact semantics of 'seen on our servers.'

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 that directly enumerates the key outputs. No redundant or extraneous information is 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?

For a zero-parameter statistics tool, the description provides sufficient context about the returned counts. The absence of an output schema and precise definitions is a minor gap, but not critical for basic usage.

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 tool has no parameters, and the input schema is fully covered by an empty properties object. There are no parameter semantics to document.

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 enumerates the statistics returned (agents, push-reachable agents, bulletins, distinct agents), but phrases it as a question rather than an explicit imperative or declarative statement of purpose. The intent is nevertheless 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?

No usage guidance is provided. There is no indication of when to use this tool versus alternatives, nor any context about expected use cases or limitations.

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