archicad_run_api_command

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

Annotations already declare destructiveHint=true and openWorldHint=false, so the safety profile is carried there. The description adds essentially no behavioral context beyond that - it does not warn that some commands mutate the model, does not state what happens on failure, and does not describe the response, which matters for a generic pass-through runner.

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?

Two short sentences, front-loaded with the core action and immediately followed by concrete examples. Efficient with no filler, though the external-reference pointer is the only content of the second half.

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 an open-ended command runner with a nested free-form parameter object and no output schema, the description is thin: it omits how to discover valid commands, how the arbitrary 'parameters' payload is shaped, and what the call returns. An agent is left to guess or leave the tool context entirely.

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 50%: 'command' is described in the schema, but the nested 'parameters' object has no description anywhere. The description compensates only weakly by redirecting to Graphisoft's reference, adding no syntax or structure for the parameter payload, so it lands at the baseline for partial coverage.

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 ('Runs an official Archicad JSON API command') with concrete examples ('API.GetElementsByType'). It is clear what the tool does, but it does not differentiate itself from the near-identical siblings tapir_run_command / tapir_describe_command, so an agent cannot easily tell which runner to pick.

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?

There is no when-to-use, when-not-to-use, or alternative guidance. 'See Graphisoft's JSON API reference for parameters' is a pointer to external documentation, not usage direction, and it never mentions the sibling discovery tools (tapir_list_commands, tapir_describe_command) an agent would need to find valid commands.

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