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

Annotations already declare this as a safe, idempotent, closed-world read, so the marginal burden is low, and the description adds genuinely new behavior: partial answers are accepted, unanswered checks echo their wording back, and scoring is deferred until all 14 are answered. It also discloses the shape of the response (fixes ordered by importance plus a brief). It stops short of explaining how fixes are ranked or what the brief contains.

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 core capability and the 0–100 outcome are front-loaded, and the second sentence covers when-to-use plus partial-answer behavior with little waste. The first sentence is a long comma-heavy list that could be trimmed, but overall the structure is functional.

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 four-parameter, nested-object tool with no output schema, the description covers the input contract (optional, partial allowed), the output contract (ranked fixes plus a written brief) and the completion rule for producing a score. Only the relationship to the sibling planning tool and the fix-ordering logic remain unexplained.

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% and each of the 14 checks, studio_type, project_count and journal carries its own description with enum and default documented, so the schema does the heavy lifting. The description reinforces the optional nature of answers but adds no meaning beyond what the schema already states.

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?

"Scores an architecture or interior design studio website out of 100 from 14 yes / partly / no checks" names a specific verb, a specific target and the inputs, then enumerates the check families (project pages, plans and drawings, photography, phone layout, share previews). It also states what comes back — ranked fixes and a written brief — so the agent knows the tool's output before touching the 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?

"Use when someone wants their studio or portfolio website reviewed" gives a clear triggering condition, and the description spells out the partial-input workflow (send what is known; unanswered checks come back; the score only appears at 14/14). It does not mention when to prefer the sibling plan_studio_website_pages instead, so the routing guidance is incomplete.

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