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

The description explicitly and prominently discloses read-only behavior: 'writes nothing, changes nothing.' This is especially valuable because annotations do not assert readOnlyHint. It also lists the return payload components, giving the agent a clear behavioral model. Although readOnlyHint is false in annotations, this reads as an absent hint rather than a positive contradiction.

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 short and front-loaded with the most decision-relevant fact (read-only). The redundancy of 'READ-ONLY' plus 'writes nothing, changes nothing' costs a minor point, but overall every sentence earns its place and the follow-up action is stated cleanly.

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 covers purpose, safety, outputs, and the next sibling to call, which is strong for a three-parameter analysis tool with no output schema. However, the variant parameter is completely unexplained, and the phrase 'facts you already stated' is vague about prerequisites or how a resume's facts are supplied. These are meaningful gaps for an agent deciding how to invoke the 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?

Schema coverage is only 67%: limit and job_description have schema descriptions, but variant has none. The description adds no parameter-level meaning and does not compensate for the undocumented variant field. The phrase 'against a posting' only echoes job_description's existing schema description rather than enriching it.

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 clear, specific operation: gap analysis against a job posting, with concrete outputs (matched keywords, missing ones, coverage figure, orderings). It also disambiguates from the sibling resume_create by framing that tool as the follow-up action. This is a strong, distinct purpose statement.

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 the context: run this analysis against a posting before acting with resume_create. It names the relevant sibling and frames the sequencing. It does not explicitly state when not to use the tool, but since no other sibling performs gap analysis, the exclusions are not necessary.

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