identify_machine

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

With no annotations, the description carries full burden. It discloses idempotent behavior ('calling again returns same mint_id with created: false') and what is returned (mint_id and wallet_address). However, it does not mention side effects, auth requirements, or rate limits. Still, it provides useful behavioral context.

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 well-structured, front-loading the purpose, then providing examples, then idempotency, then usage guidance. It is slightly long but every part earns its place. Could be more concise without the extensive list of OEMs, but that adds clarity.

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 that the tool has an output schema (mentioned in context signals), the description need not explain return values in detail. It covers core functionality, usage context, and behavior. The optional parameters are not explained, but the core is complete.

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 mentions oem, model, serial as key triple, but does not explain the optional parameters site and metadata. The description adds some meaning for required parameters but incompletely covers all five.

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: 'Provision or retrieve a persistent on-chain identity (mint_id) for any industrial machine.' It specifies the verb (provision/retrieve), the resource (on-chain identity), and distinguishes from sibling tools by stating it should be called before normalize_telemetry or create_automation.

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 includes a 'USE WHEN' section that specifies when to use the tool: when a user references a specific machine by OEM/model/serial and needs a stable handle. It also advises to call this first when a new machine is introduced. While it doesn't explicitly mention when not to use it, the context is clear.

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