lookup_order

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

No annotations are supplied, so the description carries the full behavioral burden. It never states that the operation is read-only, what happens for an unknown order ID (empty result vs. error), or whether any permissions apply; "simulated" is the only behavioral signal and it only characterizes the data, not the call's 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?

Two short sentences, front-loaded with the purpose before the parameter hint; nothing is padded. The second sentence is slightly ambiguous ("Use order ID ORD-100" could be read as a fixed value rather than a format example), costing one point.

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 read tool this is nearly adequate, but with no annotations and no output schema the description should say what a successful lookup returns and how a miss is reported. As written, an agent can form the call but cannot predict the result or failure mode.

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% — the schema only declares order_id as a bare string — so the description must compensate. The example "ORD-100" usefully conveys the expected format/prefix, but it does not clarify case sensitivity or whether the ORD- prefix is mandatory, leaving interpretation to the agent.

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?

"Look up a simulated order" names a specific verb (look up) and resource (order) and flags that the data is simulated/mock, which tells an agent what to expect back. It stops short of 5 only because there is no scope detail (single order vs. list) beyond the singular noun and no sibling differentiation to provide.

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 when-to-use guidance, no prerequisites, and no alternatives (there are no siblings, but there is also no statement of what this tool is for versus other retrieval paths). The only actionable instruction is the ID format hint, which is parameter-level rather than usage-level.

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