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

Annotations already cover the safety profile (readOnly=false, idempotent=true, destructive=false, openWorld=false), so the bar is lower, yet the description still adds substantial context: the save is atomic, the call queues a hosted job, human approval and warning acknowledgement are mandatory, revision checks guard against concurrent edits, and the approval fields must not be fabricated. This goes well beyond what the structured annotations convey.

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 tight sentences, front-loaded with the core action and artifact, then the scope exclusion, the job/retrieval model, and the approval warning. Almost no waste, though the approval caveat is somewhat redundant with the required approval parameter and could be folded in.

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 mutation tool with 18 required parameters, 11% schema coverage, and no output schema, the description handles the safety workflow and job lifecycle well and correctly points to get_job for results. It does not, however, explain the weighting-specific parameters (trim, tolerance, maxIterations, targets), leaving an agent with insufficient guidance to invoke the tool correctly without outside knowledge.

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 only 11% across 18 required parameters, so the description must compensate and it does so only partially. It implicitly explains the non-obvious safety parameters (previewFingerprint, approval, acknowledgedWarningCodes, expectedRevision) and the output artifacts (weightId/weightName), but says nothing about trim, tolerance, maxIterations, targets, targetVariable, baseWeightId, or tableIds, which materially affect the raking result.

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 and resource: it recomputes a reviewed weighting fingerprint and atomically saves a new sampling-weight column and definition. It also carves out scope by stating it "does not authorize ordinary or complex-survey inference," which separates it from run_complex_survey_method. However, it never names preview_raking_weights, its most obvious sibling, so the differentiation from the preview/review path is left to inference.

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?

It gives a clear precondition ("Obtain actual user approval before calling; do not fabricate approval fields") and redirects result retrieval to a named alternative ("use get_job to retrieve its result"). It also states a negative case (not for ordinary or complex-survey inference), though it never explicitly tells the agent to run preview_raking_weights first, despite requiring a reviewed fingerprint.

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