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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description usefully adds the payload contents (before/after values, rationale, evidence, decision/publication status) and a security guarantee ('Never contains secret values'), but says nothing about pagination or the meaning of result_offset despite that parameter existing.

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, front-loaded with the verb and resource, followed by the returned fields. No filler, though the colon list of return contents is dense and squeezes in payload detail that could be split for readability.

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, describing the returned fields is valuable and done well, and the secret-exclusion note covers a key safety concern. However, with 0% schema coverage and an unexplained result_offset, the definition is not fully sufficient for correct invocation.

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, but it only gives meaning to service_change_id (its source in list_service_changes). project_id is never explained as a scoping key, and result_offset is not mentioned at all, leaving an unexplained pagination parameter in a three-parameter tool.

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 ('Read one service proposal') and scopes it by the exact key ('by service_change_id'), which separates it from the sibling list_service_changes. It does not distinguish itself from the similarly named read_change, so it stops short of full sibling differentiation.

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 'by service_change_id from list_service_changes' implies the workflow: list first, then read a single proposal. There is no explicit when-not guidance and no statement of how it differs from read_change or read_changes_summary, leaving the agent to infer the selection rule.

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