bitop

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

With no annotations, the description fully carries the burden and does so thoroughly: it discloses output formats (unsigned, signed, hex, octal, binary), distinguishes logical vs arithmetic shift, and specifies overflow behavior. The concrete 0x80 example clarifies how results are computed.

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: the first sentence states scope, the second covers output representation, and the third explains critical edge cases. Every sentence adds useful information with 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?

The description covers the central complexity: operations, widths, output representations, shift distinctions, and overflow behavior. Since there is no output schema, the return-format description is especially valuable. It falls just short of full completeness because it does not document error behavior for invalid op values or clarify operand requirements for all operations.

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 lists valid operation names, width options, and uses the '0x80 shr 1' example to imply operand roles for a and b. However, it does not explicitly state which operations require b or how b is used in shifts, leaving a small gap.

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 providing bitwise operations, listing specific operations ('and or xor nand nor xnor not shl shr sar rol ror') and supported widths (8/16/32/64). It distinguishes itself from siblings like base_repr or bit_analysis by focusing specifically on performing bitwise computations with multi-base output.

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 tool's intended usage is implied by the operation list and examples, but there is no explicit 'use this when...' guidance or comparison to alternative tools. The shift semantics example ('shr is logical; sar is arithmetic') gives helpful context but does not address when to prefer this tool over sibling utilities.

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