Raw herdr-core call

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

No annotations are provided, so the description carries the full behavioral burden. It usefully states that server.stop and server.restart are refused because they affect every terminal, but it does not warn that other listed methods such as doc.set or machine.rm may mutate state, nor does it mention auth, errors, or side effects for arbitrary methods.

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?

Three compact sentences, front-loaded with the capability and selection rule. Each sentence adds routing guidance, concrete examples, or a safety constraint without repetition.

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 generic RPC escape hatch with no annotations or output schema, the description covers selection, example methods, discovery via rpc.discover, and a key refusal. It still leaves auth/error behavior and mutation risk for non-refused methods unstated, so it is strong but not fully 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 coverage is 0%, and neither parameter is described in detail. The method examples add some meaning by showing the JSON-RPC name format, and rpc.discover is cited for per-method schemas, but the params object and method-specific parameter structure are left for the agent to discover.

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?

States a specific verb and resource: 'Call any herdr-core JSON-RPC method directly.' It distinguishes itself from dedicated sibling tools by saying it is for methods without a dedicated tool, and the examples make the scope concrete.

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?

Explicitly defines when to use it ('For methods without a dedicated tool'), names example methods, points to rpc.discover for schemas, and states that server.stop and server.restart are refused. This covers alternatives and exclusions clearly.

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