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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the useful behavioral detail that no job description is required, which clarifies the tool's non-dependency. It does not add further behavioral traits like rate limits or error handling, but given the annotation coverage, the description's modest addition is acceptable. No contradiction with annotations.

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 a single, well-structured sentence that front-loads the core purpose and then succinctly covers the input modalities. Every phrase adds value—'without needing a job description' is a key differentiator, and the enumeration of input types is efficient. No fluff or redundancy.

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 tool has six parameters with full schema descriptions and an output schema (though not shown), so the description does not need to explain return values. It covers all input paths and the specific use case (no JD required). For an agent deciding how to call it, the description combined with the schema is sufficient; nothing critical is missing. A minor gap is that it doesn't hint at the output structure, but the output schema presumably covers that.

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?

The input schema has 100% description coverage, so every parameter already carries a clear explanation (e.g., 'Base64 encoded content of the resume document', 'Plain text or markdown content'). The tool description does not add extra meaning beyond what the schema provides; it merely summarizes the input choices. With high schema coverage, the baseline of 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?

The description states a specific verb ('Calculate'), a clear resource ('ATS compatibility score and structural audit for a resume'), and a distinct scope ('without needing a job description'). It distinguishes itself from sibling tools like civify_parse_cv (which parses) and civify_tailor_cv (which tailors) by focusing on scoring. The input flexibility (file path, JSON, text) is also mentioned upfront, making the purpose unmistakable.

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 provides clear context on when to use the tool (when no job description is available) and even gives environment-specific guidance on which input parameter to choose (resume_text for AI agents, file_base64 for remote/cloud, server_file_path for local). However, it does not explicitly name alternatives or state when NOT to use it (e.g., when a job description is available, one might use a different tool). This is good but lacks explicit exclusions.

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