Inscribe Binary Content

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

Annotations provide the safety profile (readOnlyHint=false, destructiveHint=false). The description adds valuable behavior beyond that: 'Bytes are inscribed untouched' indicates no transformation of the binary data. It also discloses that this is a preparation step by saying 'Returns prepared inscription; broadcast with ordnet_inscribe_broadcast,' which clarifies the non-final nature of the action. Slightly more detail (e.g., side effects or permission requirements) could push it higher, but this is solid with annotation support.

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: a clear opening sentence, a behavioral note, a supported-types list, and an Args block. It is not excessively long, but the Args block somewhat duplicates the schema and could be trimmed without loss. However, every sentence carries useful information, and the front-loading of the core purpose is effective.

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, the description steps up by stating the return type ('Returns prepared inscription') and connecting the workflow with ordnet_inscribe_broadcast. It also covers supported MIME types and parameter constraints. It lacks details about limits (e.g., maximum file size) or edge cases, but given the tool's simplicity and rich sibling context, this is adequate and only slightly incomplete.

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 100%, so the baseline is 3. The description's Args section largely repeats the schema: contentBase64, contentType, feePerByte. It does add 'default 0.15' for feePerByte and reinforces that contentBase64 is base64-encoded, but these are already present in the schema. No additional parameter semantics beyond the schema are provided, so it stays at the baseline.

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 opens with a specific verb+resource: 'Prepare an inscription for BINARY content (images, audio, video, PDF) from base64.' It clearly distinguishes itself from sibling tools by explicitly naming ordnet_inscribe_prepare and saying to use this for anything that is not text. The supported MIME type list further scopes the tool's 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?

Explicit usage guidance is provided: 'use this instead of ordnet_inscribe_prepare for anything that is not text.' It also lists supported content types (e.g., image/png, application/pdf) and directs the user to the next step in the workflow: 'broadcast with ordnet_inscribe_broadcast.' This gives clear when-to-use and workflow context.

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