bosch_get_soc

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

No annotations are provided, so the description must cover behavioral traits. It discloses requirements (ConnectModule), availability conditions, and live API behavior. It also lists the return fields. This provides adequate transparency for a read operation.

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 concise and well-structured. It uses bullet points for returns and a separate 'Args' section for the parameter. Every sentence adds value without redundancy.

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 simplicity (one parameter), the presence of an output schema, and the description covering purpose, requirements, and parameter semantics, the description is fully complete. No gaps remain.

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%, but the description adds a clear parameter description: 'bike_id: The bike UUID from bosch_get_bikes.' This explains the parameter's source and meaning, fully compensating for the lack of schema documentation.

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: 'Get live state-of-charge from the Bosch ConnectModule.' It lists specific returned data (battery percentage, charging status, remaining energy, reachable range per assist mode). This distinguishes it from siblings like bosch_get_batteries and bosch_get_capacity.

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 provides context on when to use the tool: requires a ConnectModule, data available only when bike is powered on/charging/recently active. It notes the API is live with no caching. While it doesn't explicitly state when not to use, it gives sufficient guidance for correct usage.

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