archicad_modify

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description earns credit for adding beyond them: it explains that results are per-item, that individual items can fail independently, and that the result must be read. The restricted-command policy is genuinely useful behavioral context that annotations cannot express.

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 short sentences with no filler, and the core purpose is front-loaded ahead of the batching and policy caveats. Minor lost opportunity in not pairing the restriction note with a pointer to the schema/search siblings.

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 no output schema, the description does sketch the return shape (one entry per item, per-item failures), which is helpful. But for a tool whose entire payload is an untyped command string plus an untyped parameters object, leaving command discovery and the parameters contract unexplained is a material gap.

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% across all three parameters, so the description must carry the burden and largely doesn't. The two example command names give a hint about 'command', but 'port' is never mentioned and the free-form 'parameters' object is never explained (e.g. whether it is a single object or a list matching the batched items).

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 a command that changes the project') and gives two concrete example commands, which cleanly separates it from the read-only sibling archicad_read. It stops short of explicitly calling out that distinction, but the mutating scope is unmistakable.

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?

Gives real operating guidance: batch many items into one call, and note that QuitArchicad/CloseProject are refused unless the full policy is enabled. It never tells the agent how to discover valid command names or parameter shapes, even though archicad_search_commands and archicad_command_schema exist as siblings for exactly that purpose.

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