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

Adds critical behavioral context not in annotations: async nature requiring polling, credit costs (10 cr vs 5 cr), and CV parsing prerequisites. Annotations indicate non-idempotent write operation (readOnlyHint: false, idempotentHint: false), which aligns with 'Start' language. Does not disclose duration estimates or error states, preventing a 5.

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?

Four dense, information-rich sentences with zero waste. Front-loaded with action and return values, followed by polling workflow, prerequisites, and cost structure. Every clause earns its place in the async workflow explanation.

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 an async job initiation tool without output schema, the description comprehensively covers the full lifecycle: initiation, polling mechanism, result retrieval (two alternative methods), prerequisites, and cost implications. Sufficient for correct agent orchestration.

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 has 100% coverage establishing baseline 3. Description adds valuable credit cost metadata ('10 cr', '5 cr') for the analysis_type enum values, aiding agent cost-benefit decisions. Could reference context_id/candidate_id acquisition beyond schema descriptions for higher score.

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 explicitly states the tool 'Start[s] an async GEM (10-factor competency) analysis' with specific resource (GEM analysis) and scope (10-factor competency). It distinguishes itself from siblings like atlas_start_jd_analysis or atlas_start_fit_match by specifying the GEM/competency focus and analysis types (gem_full, gem_lite, career_path).

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?

Provides explicit prerequisites ('Candidate CV must be fully parsed first -- verify with atlas_get_candidate') and complete workflow guidance ('Poll with careerproof_task_status(task_id) until status=completed, then fetch results with atlas_get_analysis...'). Names specific sibling tools for polling and result retrieval, creating a clear usage chain.

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