get_page_architect

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds that results are "complete layout scaffolds with explicit slot markers," which is useful output-shape context. It says nothing about how the many alias parameters (id/name/block/recipe/componentId) resolve or which wins, which is the main behavioral ambiguity.

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 clauses, front-loaded with the stage tag and the core verb+resource, with almost no waste. The bracketed stage label is slightly cryptic but earns its place by flagging pipeline position.

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 read-only retrieval tool with no output schema and 8 optional alias parameters, the description covers the basic contract but omits resolution precedence among aliases and how search matching works. Adequate but with clear 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 100%, so the schema documents every parameter including enums for density and environment. The description adds no meaning beyond that, so the baseline 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?

States a concrete verb and resource ("Search and retrieve complete layout scaffolds with explicit slot markers") and openly discloses that it is an alias of basecoat_page_architect, which prevents the agent from treating the two as separate capabilities. It does not, however, draw a clear line against sibling retrievers like get_macro_block or search_macro_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 "[STAGE 1: ARCHITECT]" prefix implies this is the first step in a pipeline, which is weak but real usage context. There is no explicit when-to-use vs. when-not guidance and no mention of when to prefer this over basecoat_page_architect (its own base tool) or the block-level retrieval siblings.

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