architect_sdd_check

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

readOnlyHint, idempotentHint and destructiveHint=false already declare the safety profile, so the description's 'without accepting or changing state' is largely restatement, though 'accepting' adds useful nuance that nothing is committed. It says nothing about what happens if no sdd-workspace.yml exists, whether checks are recomputed or cached, or how failures are surfaced.

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, no filler, with the read-only constraint in the trailing clause. It is efficient but the front-loaded portion is the vague part, and the informative 'without accepting' qualifier is buried at the end.

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 checker with no output schema, the description should convey what comes back (pass/fail, findings, freshness verdicts), and it only gestures at that via three abstract nouns. Combined with the undocumented change_id, an agent knows roughly the intent but not the expected return or the optional-parameter behavior.

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 50%: workspace is documented, but change_id has no description anywhere. The description never mentions change_id, so it adds no meaning about whether it scopes the checks to a specific change or is optional for a workspace-wide check.

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 verb is 'read' and the objects are named loosely as 'deterministic checks, regression readiness and freshness', but the underlying resource is never pinned down (a check result? a readiness report?). With siblings like architect_sdd_prepare_check, architect_style_check and architect_sdd_read present, the description gives no basis for telling them apart.

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 phrase 'without accepting or changing state' hints that this is a non-committal inspection pass, but no alternative is named and no condition is given for choosing it over architect_sdd_prepare_check or architect_sdd_read. The agent must infer the workflow position from the tool name alone.

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