design-engine

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

With no annotations provided, the description carries the full burden of disclosing behavior. It only states the action ('Mark as acknowledged') without explaining what that means systemically—whether it's idempotent, reversible, changes message state, or triggers side effects. No safety or error behavior is disclosed.

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, clear sentence with no redundancy. It is appropriately concise for a simple, single-action tool. 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 tool with one parameter and no output schema, the description is too sparse. It lacks behavioral transparency and parameter semantics, and provides no usage guidance beyond the core action. It does not cover typical operational questions an agent would need to invoke 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 coverage is 0%, and the description does not mention messageId at all. While the schema provides format and pattern, the description fails to explain that messageId identifies the message to acknowledge. The parameter is inferable from context but not explicitly described, leaving room for 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?

The description uses a specific verb ('Mark') and resource ('a message addressed to this agent') with clear scope. It distinguishes from siblings like agent_board_reply (which implies a response) and agent_board_post (which creates a new message). The purpose is unambiguous.

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

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

The description implies usage: it should be used to acknowledge messages directed at this agent. However, it provides no explicit guidance on when to prefer this over agent_board_reply or agent_board_inbox, nor does it mention any preconditions or alternatives. Usage is inferable but not 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?

Without annotations, the description must disclose behavioral traits, but it only says 'Read encrypted messages.' It does not clarify whether messages are returned decrypted, whether reading changes message status, pagination behavior, or any security prerequisites. 'Encrypted' describes the content, not the tool's 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, front-loaded sentence that efficiently conveys the core action and object without redundancy. It is appropriately concise for the tool's simplicity.

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 three optional parameters, the description is underspecified. It does not explain return format, filtering semantics, or the meaning of status/threadId, leaving significant gaps for such a 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%, so the description should explain the parameters (limit, status, threadId), but it does not mention any of them. Although the schema provides types and an enum, the description adds no semantic meaning to these parameters.

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

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

The description clearly states the action (Read) and the resource (encrypted messages addressed to this configured agent), which unambiguously distinguishes it from sibling tools like agent_board_post, agent_board_reply, and agent_board_ack. It is specific and not a tautology.

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 use for reading inbox messages but does not explicitly state when to use it vs. alternatives or provide exclusions. The sibling names suggest other actions, but no direct guidance is given, so usage is only implicitly conveyed.

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 disclosure burden. It reveals two important behaviors: encryption and key requirement. But it remains silent on idempotency guarantees (despite the idempotencyKey), message expiration (despite expiresInSeconds), and whether posts are addressed to a recipient (recipientAgentId), leaving significant behavioral gaps.

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

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

Two sentences totaling under 25 words. The sentence is front-loaded with the action and uses precise qualifiers ('encrypted,' 'agent-to-agent,' 'configured free agent-board key'). 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 tool with 6 parameters, no annotations, and no output schema, this description is too sparse. It does not clarify return behavior, error conditions, idempotency semantics, or how recipientAgentId interacts with topic, making it difficult to use correctly in varied 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 has 0% property descriptions. While the description's 'request, response, or notice' maps to the kind enum, it does not explain the semantics of idempotencyKey, topic, payload, expiresInSeconds, or recipientAgentId. The agent must infer from names/constraints, which is insufficient for correct invocation.

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

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

The description explicitly states the action: 'Post an encrypted agent-to-agent request, response, or notice.' This clearly differentiates from siblings like agent_board_reply and agent_board_ack by indicating a posting action covering the three kinds listed in the enum, making the purpose unambiguous.

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

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

The description gives a clear context for use ('post...request, response, or notice') and a prerequisite ('Requires a configured free agent-board key'). However, it does not explicitly contrast with sibling tools or state when not to use it, so it stops short of full 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, the description must carry the full behavioral disclosure burden. It mentions 'visible encrypted' but does not explain idempotency, expiration, side effects, required permissions, or return behavior. Critical information for a mutation tool is missing.

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 immediately identifies the action and target, earning its place efficiently.

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

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

For a tool with 5 parameters, no annotations, and no output schema, this one-sentence description is incomplete. It does not address idempotency, expiration, payload expectations, or how replies relate to the message lifecycle.

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 adds no meaning to the parameters (messageId, idempotencyKey, topic, payload, expiresInSeconds). Parameter names and schema constraints are the only information available, so the description fails to compensate.

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 ('Reply') with a clear resource ('agent-board message') and adds key constraints ('visible encrypted'). This distinguishes it from sibling tools like agent_board_post (posting new messages) and agent_board_ack (acknowledging).

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

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

The description gives no guidance on when to use this tool versus alternatives such as post or ack. It implies replying to received messages but does not state prerequisites, exclusions, or relationships to sibling tools.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the tool 'generates' a design basis, which implies a non-destructive computation, but it does not disclose any performance characteristics, side effects, or prerequisites. It adds minimal behavioral context beyond what is obvious from the verb 'Generate'.

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, well-structured sentence that leads with the action ('Generate') and clearly enumerates the key inputs. It is concise, free of filler, and every phrase adds value. The structure front-loads the most important information and immediately conveys the tool's purpose.

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 complex tool with 9 parameters, nested objects, and an output schema, yet the description is very brief. It does not explain what 'profile-aware' means, what the generated 'design basis' contains, or how optional inputs like parcels and custom inputs affect the result. The description is not sufficient for a user to fully understand the tool's capabilities without additional investigation.

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 should compensate by explaining parameter semantics. It lists main inputs like 'IT load', 'rack density', and 'GPU generation' but gives no units, constraints, or interaction details. 'Optional project inputs' is vague and does not map to specific schema properties. The description adds little beyond the parameter names themselves.

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 function with a specific verb ('Generate') and a precise deliverable ('AI data center design basis'). It lists the key input parameters, distinguishing it from sibling tools like layout and validate through its focus on generating a design basis rather than producing a layout or performing validation.

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 used when a design basis is needed from the listed inputs, but it does not explicitly discuss when to prefer this tool over layout or validate. There is no mention of exclusions or alternative tool selection, leaving usage context implicit rather than explicit.

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

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

Without annotations, the description partially discloses output types but omits behavioral traits such as whether it is destructive, read-only, or performance-intensive. It mentions generating data but not side effects.

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?

Single sentence, front-loaded with verb, but omits essential details. Acceptably concise for minimal viability but lacks substantive structure.

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

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

Given the tool's complexity (nested input schema, multiple parameters) and lack of annotations, the description is too brief to provide complete context. It does not cover parameter meanings or usage context adequately.

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

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

Schema description coverage is 0%, and the description does not explain any parameters. The only reference is 'from a nested design request,' which is insufficient to clarify the complex 'design' object with many required fields.

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 it generates rack blocks, rack-plan candidates, and site layout data from a design request. It distinguishes it from sibling tools like 'design' and 'validate' by specifying the output 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?

No guidance on when to use this tool versus alternatives. It implies input from a design request but does not explicitly state prerequisites or compare to siblings.

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

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

With no annotations provided, the description carries full burden. It mentions that private EngineSessions are not exposed through public MCP, which is a minor behavioral constraint, but it fails to disclose idempotency, side effects, or whether the tool is read-only. The description is insufficient for a validation 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 short (two sentences) and front-loaded with the main purpose. However, the second sentence about private sessions is tangential and could be omitted or moved to a more appropriate section. Still, it avoids unnecessary verbosity.

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

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

Given the tool's complexity (multiple parameters, nested objects, output schema), the description is minimal. It does not explain prerequisites or validation outcomes, but the presence of an output schema partially mitigates the need to describe return values. The description is adequate but not comprehensive.

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% for individual parameters. The description only mentions the two top-level input categories (designSummary and rawInput) without explaining their properties or constraints. It adds minimal meaning beyond the schema, which is inadequate given the low coverage.

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

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

The description clearly states that the tool validates designs against specific rule categories (electrical, cooling, etc.). It specifies two distinct input types (design summary or raw input) and uses a precise verb-resource pairing, distinguishing it from sibling tools like 'design' and 'layout'.

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 that validation is performed on a design, but it does not explicitly state when to use this tool versus creating or laying out designs. No alternatives or exclusions are mentioned, leaving the agent to infer usage context.

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