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

No annotations exist, so the description carries the full burden of behavioral disclosure. It states the copy operation and file types, but does not disclose whether it overwrites existing assets, modifies the .aia archive, whether the source remains untouched, or what success/failure returns look like. For a mutating tool with no annotation safety hints, this is a notable 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?

A single sentence conveys the verb, object, destination, and example file types with zero wasted words. It is front-loaded and immediately useful.

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 a simple tool with highly documented parameters and no nested objects, the description plus schema is mostly sufficient to call it correctly. However, the absence of an output schema means there is no explanation of what the tool returns, and side-effect behavior is also unaddressed, leaving moderate uncertainty for an agent.

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 100% for all three parameters, so the schema already documents them. The description adds no new details beyond naming the asset folder, so it does not improve or compensate for parameter meaning beyond the schema baseline.

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 uses a specific verb ('Copy') with a clear resource ('a local file') and destination ('the project's assets folder'), plus a parenthetical of asset types. It is immediately distinguishable from sibling tools like aia_add_screen, aia_add_component, and aia_set_blocks.

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 gives clear context: this tool is for embedding local files into a project's assets. It doesn't explicitly name alternatives or exclusions, but the operation it describes is sufficiently distinct from all sibling tools that an agent can infer when to use it.

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?

With no annotations provided, the description must disclose behavioral traits like whether the .aia file is modified, whether the operation is destructive or reversible, or how duplicate names are handled. The description only restates the high-level action ('Add a UI component') and does not reveal these side effects or constraints.

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 a single, focused sentence that front-loads the primary action and then notes the optional nesting behavior. It contains no filler or extraneous words.

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?

This is a mutating tool with no annotations and no output schema. The description and schema together document what parameters exist, but they do not clarify the operational impact on the .aia file, prerequisites like an existing screen, error behavior, or what constitutes a successful result. A more complete description would mention that it modifies a project file and requires valid component types and a writable path.

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 83%, so the existing parameter descriptions already document most inputs. The description adds minor context by mentioning 'parent arrangement/component', which reinforces the purpose of parent_name, but it does not add meaning beyond the schema for other parameters like path, type, or props_json.

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 specific verb and resource: 'Add a UI component to a screen'. It also conveys the optional nesting behavior, which distinguishes this tool from sibling tools like aia_add_screen (adds a screen) and aia_set_property (modifies existing properties). An agent can tell what this tool does without ambiguity.

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 implies usage context: use this when you need to place a new UI component on a screen, optionally inside a parent component. However, it does not explicitly state when not to use it or mention alternatives, leaving some inference to the agent.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It discloses that it appends rather than overwrites, and it describes the two supported actions: setting a property or opening a screen. It does not mention duplicate event handling, in-place file modification, validation failures, or other side effects, so some behavior remains opaque.

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 compact and front-loaded with the tool's exact purpose, followed by a dense summary of action shapes. It is not overly long, but the second sentence is technical and packed, sacrificing a little readability. No wasted words overall.

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 tool with nested schema objects and no annotations, the description should clarify how to construct an event handler and what happens if an event already exists or an action is invalid. The example 'when Button.Click do...' helps, but the agent may still struggle to shape the events argument reliably without additional context.

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 schema description coverage is only 33%, so the description does important work by explaining the action shapes: {set, component, componentType, to} and {openScreen}. However, it does not clearly map those actions to the actual `events` array structure or clarify `screen_name` and whether the events are keyed by component and event. Some inference is still required.

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 specifies the verb (generate and append), the target resource (screen's blocks), and the artifact (event handlers). It also signals non-destructive behavior with 'without touching existing ones', which differentiates it from sibling tools like aia_set_blocks. However, it does not explicitly name the sibling or contrast with it, so it is clear but not maximally differentiated.

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 'append' language and 'without touching existing ones' imply that this tool is the right choice when the agent wants to add new event handlers while retaining existing blocks, rather than replacing them. Yet the description does not explicitly state when to use this tool versus alternatives, nor does it mention any conditions or exclusions.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'Add' which implies mutation, but it does not state side effects such as in-place file modification, backups, or validation behavior. There is no indication of permissions or failure modes.

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 a single, front-loaded sentence with no wasted words. It states the action and the required target context efficiently.

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?

The description is adequate for a simple add operation, and the schema documents most parameters. However, since this is a mutating tool with no annotations and no output schema, some behavioral context such as whether the .aia file is updated in place or whether the screen name must be unique would make the definition more 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?

The schema covers path and title, but screen_name has only its type declared. The description adds little beyond the schema, although the tool name and phrase 'new screen' indirectly make screen_name self-explanatory. At 67% coverage, the description does not strongly compensate for the undocumented parameter.

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 specific verb and resource: 'Add a new screen to an existing .aia project.' It clearly distinguishes this tool from siblings like aia_create_project (creating a project) and aia_get_screen (reading a screen).

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 gives clear context by specifying 'existing .aia project,' which implies it should not be used for project creation. However, it does not explicitly name siblings or state exclusions.

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?

No annotations are provided, so the description must stand alone for behavioral disclosure. It does reveal the mutation (create), the resulting state (empty project with Screen1), and an important sanitization side effect ('Name is sanitized to letters/digits/underscore'). It does not say what happens if the path already exists, which is a minor gap for a creation tool.

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 one sentence that packs the core action, the resulting scope, and the name constraint into a single, properly front-loaded statement. Every clause earns its place, with no filler.

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 and no available annotations, the description gives an agent the primary creation expectations: a new project file is created, with exactly one Screen1, and the provided name will be sanitized. It is slightly incomplete around overwriting or existing paths, but is otherwise sufficient for a simple two-parameter creation tool.

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 schema already covers both parameters with 100% description coverage, so a baseline of 3 applies. The description adds extra semantics by explaining project_name is sanitized and that the project starts with Screen1, which helps an agent reason about allowed project names without inspecting behavior. It does not add deeper meaning to path, but the schema already defines it adequately as an absolute or relative .aia file path.

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 names a specific verb-create-plus-resource, 'Create a new empty .aia project', and adds the key initialization detail 'with a Screen1'. It is also clearly distinct from sibling tools like aia_add_screen or aia_inspect, so an agent knows exactly what this operation produces.

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 intended use is clear: call this when starting a brand-new project at a given .aia path. It does not explicitly state when not to use it, such as pointing to aia_add_screen for adding extra screens, but the context of creating an empty project with Screen1 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?

With no annotations, the description carries the burden and it does establish that this is a read-style operation returning components, properties, and blocks XML. It does not disclose failure behavior, path/screen_name validity expectations, or whether any side effects could occur, though the read nature lowers risk.

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?

A single, front-loaded sentence uses the verb 'Read' first, identifies the resource, and lists exactly what is returned. There is no filler or redundant content.

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?

The description gives what it delivers (component list, screen properties, blocks XML) and the schema covers one of the two parameters. The only real gap is the undocumented screen_name parameter and the lack of explicit distinction from aia_inspect, but for a small read tool this is mostly adequate.

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?

Only the path parameter has schema documentation (abs/relative .aia file). The screen_name parameter has no schema description, and the description does not compensate by explaining what screen_name should be (e.g., expected format or valid values). The output content is described, not the input semantics.

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 has a specific verb ('Read'), a target resource ('one screen'), and enumerates the returned contents ('component list, screen properties and blocks XML'). It clearly distinguishes the tool from the mutation-oriented siblings, though it leaves how it differs from aia_inspect implicit.

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 guidance about when to use this over aia_inspect or when not to use it. No prerequisites, alternatives, or exclusions are mentioned; usage is only implied by the word 'Read'.

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?

The verb 'List' implies a read-only, non-mutating operation, which is helpful. But no annotations are provided, so the description carries the full burden. It does not disclose behavior for invalid paths, malformed .aia files, or the structure of the returned output.

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?

One sentence with no filler. It front-loads the primary action, then lists the object types covered (screens, components, assets, properties). Every word contributes meaningful information.

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 simple listing tool with a single parameter, the description is mostly complete. The lack of an output schema is mitigated somewhat by the description naming what is listed. Still, it could benefit from clarifying that it runs a read-only inspection of the project and from mentioning behavior for invalid inputs.

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 schema already describes the path parameter as 'Absolute or relative path to an .aia file.' The tool description adds no additional semantic detail beyond that. Since schema coverage is 100%, the baseline of 3 is appropriate.

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 specific verb and resource: "List screens (with their components), assets and properties of an .aia project." This clearly communicates what the tool does. However, it doesn't differentiate from siblings like aia_get_screen, which may also expose components or properties in more detail.

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 is given on when to use this tool versus the sibling tools. There is no mention of alternatives, prerequisites, or context such as 'use this to review project structure before making edits.' The intended usage must be inferred from the verb 'inspect' and the sibling 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?

No annotations are available, so the description must carry behavioral disclosure. It does reveal a non-obvious behavior, screen collision prefixing with the source project tag, and mentions the AIA Stitch engine. However, it does not state whether the input files are read-only, how ordering affects the merge, or what happens when the out_path already exists.

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 sentences, no clutter, and the core behavior is front-loaded. The parenthetical about the engine adds useful provenance without distracting from the main description.

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 merge tool with no output schema and no annotations, the description covers the central operation and a critical collision behavior. But it leaves open questions such as what project_name controls, what the merge does with non-screen resources, and whether out_path is overwritten, so an agent has to make assumptions.

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 only 33%, and the description does not explicitly explain the semantic meaning of project_name or fully map input_paths and out_path beyond the merge concept. The description provides some inferable hints, but the required project_name parameter is left vague, so it does not compensate for the schema gap.

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?

Starts with a specific action ('Merge multiple .aia files into one') and names the resource type, clearly distinguishing it from siblings like aia_create_project and aia_add_screen. The extra detail about colliding screens being prefixed removes ambiguity about what the merge does.

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 makes the use case clear: combine multiple .aia files into a single project. It does not explicitly mention when not to use it or directly compare with alternatives, but the purpose is obvious enough in the context of the sibling 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?

With no annotations, the description carries meaningful behavioral load: 'Replace' signals destructive overwrite, and the XML-root rule warns of a top-level validation constraint. However, it does not describe success/failure behavior, whether the screen must exist first, or what side effects occur on the .aia file.

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 deliver both the operation and the key constraint without wasted words. The action and main validation rule are front-loaded and easy to parse.

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 destructive, three-parameter tool with no annotations and no output schema, the description covers the essential purpose and input contract but omits success/failure semantics, whether the screen or file must already exist, and what the agent should expect after the call. It is adequate but not fully self-contained.

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 only 33%, but the description adds substantial meaning to blocks_xml by explaining that it is a .bky blocks XML and must have an <xml> root element. It implicitly ties screen_name to the target screen, though it does not explicitly describe the parameter.

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 concrete verb 'Replace' and a specific resource: a screen's blocks XML (.bky). This clearly differentiates it from siblings like aia_get_screen or aia_set_property, which target other concerns.

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 is provided about when to use this tool versus alternatives such as aia_get_screen or aia_set_property. The 'Must' sentence states an input validation requirement, not a usage condition or context.

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?

With no annotations, the description carries the full burden for behavioral disclosure. It does reveal value type constraints and screen-versus-component targeting, but it never states whether the .aia file is mutated in place, whether properties are overwritten, what happens for invalid prop names, or what the operation returns.

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 a single, focused sentence that leads with the primary action and then adds the most important usage nuance (screen vs. component). Every clause adds information without excessive length.

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 5 parameters, no output schema, and no annotations, the description is too thin. It does not explain what prop names are supported, how to specify a screen, whether the file is modified on disk, or what errors are likely — so an agent may invoke the tool incorrectly.

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 only 20%, and the description compensates for very little. It clarifies component_name by saying to omit it for the screen itself, but it does not explain prop, screen_name, or the path beyond schema type info. The value-type mention duplicates the schema's anyOf constraint.

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 identifies the action as setting one property on a screen or component, which distinguishes it from sibling tools like aia_set_blocks. However, it does not explicitly mention that the operation targets an .aia file or contrast with related mutations, so it is clear but not fully differentiated.

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 explains a key internal usage rule — omit component_name to target the screen — but gives no guidance on when to choose this tool over alternatives like aia_set_blocks or aia_add_component. No exclusions, prerequisites, or conditions are stated.

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