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

Annotations already declare readOnly, idempotent and closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: responses may be truncated, omitted definitions are listed in moreDefinitions, and passing such a name retrieves it.

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, front-loaded with the purpose and followed by the ordering rule and the truncation workaround. Nothing is redundant.

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 small two-parameter, read-only introspection tool with no output schema, it covers the key operational quirk (truncation and follow-up calls). The unexplained 'depth' parameter is the one real 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%, so the description must carry the params. It implies that 'name' is the command or a moreDefinitions entry name by saying "pass one of those names here", but the 'depth' parameter (default 3) is never mentioned, leaving half the parameters undocumented anywhere.

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: returns a command's input and output schemas plus referenced definitions. An agent can distinguish this from siblings like archicad_search_commands or archicad_read, though it doesn't name them explicitly.

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?

"Read this before the first call of any command" gives a clear triggering condition and sequencing rule. It does not name alternatives or exclusions, but the when-to-use is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds only the enumeration of skill names; it says nothing about the form or size of the returned method, whether unknown names error or fall back to a default, or how the default "archibridge" is applied.

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 terse, front-loaded sentences with no padding. It is efficient, though the terseness tips into under-specification rather than crispness.

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?

An output schema exists so return values need not be described, but the agent still lacks the essentials: what a "working method" contains, whether it is prose instructions or structured data, and what to do with an unrecognized skill name. For a lookup tool with a 0%-documented parameter, the description leaves real gaps.

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% for the single "name" parameter, so the description must compensate. It does partially by listing the two admissible skill identifiers, but it never states that the parameter is the skill selector, nor how the schema default of "archibridge" interacts with omitting the argument.

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?

"Returns a working method" is an indirect way of saying it fetches a skill/instruction document, but the verb and resource are only loosely expressed. The enumerated skill names ( archibridge, archicad-mep-review) hint at the retrieval target, yet the agent must infer what a "working method" actually is and how it differs from archicad_search_commands or archicad_command_schema.

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?

No guidance on when this tool should be chosen over the sibling tools that also deal with commands and schemas. There is a list of available skills but no statement of what scenario calls for fetching one, or what to do when the desired skill is not in the list.

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

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

Annotations already cover read-only and idempotency, so the description correctly spends its words elsewhere: it defines the three status values ('ready', 'no_project', 'busy') and the tapir-null degradation path, which are behavioral facts nowhere in the schema. It stops short of describing output shape in detail, but the field list partially compensates.

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?

Four short lines, each doing distinct work: what is returned, when to call, what status means, what tapir=null implies. The 'Call this first' instruction is placed early where an agent will act on it.

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?

With no output schema, the description carries the return-value burden and does so adequately by naming the reported fields plus the status and tapir semantics. It could go slightly further on how to use the port value in subsequent calls, but nothing an agent needs to invoke it correctly is missing.

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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description wisely does not invent parameter guidance.

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 ('Lists the running Archicads') and enumerates exactly what each entry contains: port, version, open project, Tapir add-on version. This is clearly distinct from siblings like archicad_read or archicad_modify, which operate on a specific instance after discovery.

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?

Explicit sequencing directive 'Call this first' removes any ambiguity about tool order. It also gives a concrete conditional: when tapir is null, only API.* commands work until the add-on is installed, which tells the agent when to fall back rather than press on with other tools.

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

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.

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false. The description usefully adds that view-only commands like ChangeWindow and FitInWindow are allowed and clarifies the multi-instance port condition, though it does not describe errors or output behavior.

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 definition is front-loaded with the key non-mutating constraint and then organizes command, parameters, and port notes efficiently. It is concise, though the placement of the 'Also allowed' sentence after the port note is slightly less structured.

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 dynamic command dispatcher, the description gives examples and parameter notes but does not reference archicad_search_commands or archicad_command_schema for discovering valid commands or input schemas. With no output schema, it also leaves the return behavior implicit.

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 carry parameter meaning. It explains all three parameters at a basic level: command examples, parameters as the command's input object, and port only when several Archicads are ready. The 'parameters' explanation remains somewhat generic, but the core semantics are present.

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 states a clear verb and scope: 'Runs a command that does not change the project.' It distinguishes the tool from mutation-oriented siblings by emphasizing non-mutating behavior and examples, though it does not explicitly name archicad_modify.

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?

It gives useful context on allowed command types and when port is needed, but it does not explicitly say when to use this tool versus archicad_modify, archicad_search_commands, or archicad_command_schema. The usage is implied rather than routed.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds the empty-query-returns-groups behavior, which is genuinely useful. But the sentence about 'minimumArchicad' references a filter that has no corresponding parameter in the schema, adding confusion rather than clarity.

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?

Tight: one purpose sentence, one compact example set, and two short behavioral notes. Front-loaded and free of filler. Slight deduction because the 'minimumArchicad' sentence occupies space while conveying an ambiguous, arguably defective concept.

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?

With no output schema, the description should convey what comes back; it partly does (groups when query is empty, command matches otherwise) but doesn't say what a returned command record contains or how limit affects results. For a discovery tool an agent will chain into schema inspection, this is adequate but leaves gaps on return shape and the access filter.

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 carry the load for all three parameters. It explains only 'query' (words matched against name/group/description) and partially the empty-query case; 'limit' and especially the 'access' enum (any/read/modify/restricted) are never mentioned, which matters for an agent filtering by permission class. The stray 'minimumArchicad' reference further muddies parameter understanding.

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 ('Finds Archicad commands') plus the fields searched (name, group, description), and the examples pin down what a query looks like. It doesn't explicitly distinguish itself from siblings like archicad_command_schema, but the search-vs-inspect split is reasonably clear.

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 note 'Leave query empty to see the groups' is a real usage hint for discovery, and the examples imply the intended query style. However, there is no guidance on when to use this versus archicad_command_schema or archicad_read, and the intended search-then-inspect-then-execute workflow is left implicit.

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

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

Annotations already cover safety (readOnly, idempotent, closed-world), and the description adds genuinely useful context beyond them: window-type coverage, the need to switch windows first, and the difference between zoomed and whole-drawing capture. It does not describe the returned image format or size, which is a minor remaining gap.

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, front-loaded with the core behavior and followed by the prerequisite and the parameter note. The trailing 'entire_drawing:' fragment is slightly clipped but not wasteful.

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?

With no output schema, the description does state that the result is a picture, and annotations carry the safety profile. The main omissions are the port parameter's meaning and any hint about the image payload (format, resolution), which an agent may need to handle the response correctly.

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 carry the parameter burden. It explains entire_drawing well ('capture the whole drawing, not just the zoom') but says nothing about the port parameter, leaving one of two parameters undocumented in both places.

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 concrete verb and resource ('Returns a picture of Archicad's current window') plus the intent ('check your work'), which is enough to separate it from archicad_read and archicad_modify without opening a schema. The scope (3D and 2D windows) is stated explicitly.

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 a real prerequisite ('Switch window first with ChangeWindow if needed') and the condition that selects the entire_drawing behavior. It lacks an explicit when-not-to-use clause, but for a screenshot tool the intended use case is clear.

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