crosstabs

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds a useful behavioral constraint (deterministic, bounded) beyond annotations, but does not explain output behavior or limits beyond what the schema states. With annotations carrying the safety burden, a 3 is appropriate.

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?

A single, front-loaded sentence with zero waste. Every word contributes to the meaning.

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 8 parameters, 38% schema coverage, and no output schema explanation needed (output schema exists), the description still omits critical constraints such as the weighting prohibition (weighted must be false) and the inputSemantics attestation requirement, which are only partially covered in the schema. For a tool with this parameter complexity, the description is inadequate.

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 38%, so most parameters (rowLabels, columnLabels, percentage, rowVariable, columnVariable) have no schema documentation. The description provides no parameter-level detail at all, so it fails to compensate for the coverage gap. Baseline would be 3 only if coverage were high; here it is low and the description does not help, but it is not actively misleading.

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 (Compute) and resource (statistics from a contingency matrix) with a scope qualifier (deterministic, bounded, aggregate). It does not distinguish itself from render_crosstab or run_table, but the 'analyze' vs 'render' distinction is implied by the description's focus on statistics rather than display.

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?

No explicit when-to-use or when-not-to-use guidance. With siblings like render_crosstab and run_complex_survey_method, an agent cannot tell from the description alone when this aggregate-only tool is the right choice versus those alternatives.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false. The description adds behavior the annotations do not cover: the operation is asynchronous (it queues a hosted job) and the result must be fetched via get_job, plus the filter is 'auditable'. That is genuine added value beyond structured fields.

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?

Two sentences, no filler, with the core action front-loaded and the async follow-up second. Every sentence earns its place.

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 mutating, 7-parameter tool with a recursive nested expression and no output schema, the description covers the async result path well but omits the parameter semantics and revision/idempotency preconditions. It is adequate but leaves clear gaps an agent would need to close from the schema.

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 29% across 7 required parameters, so the description must compensate and it does not. It says nothing about expectedRevision, idempotencyKey, tableIds, projectId, or the nested definition/expression structure, leaving the agent to infer the most complex part of the call from the schema alone.

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: 'Create and assign an auditable project filter.' An agent knows this writes a filter into the project. It does not, however, differentiate itself from nearby siblings such as define_row_set, define_banner, or apply_transformation, so it stops short of a 5.

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 second sentence gives a concrete workflow instruction: 'Queues a hosted job; use get_job to retrieve its result.' That tells the agent this is async and how to follow up, which is real guidance. But it says nothing about when to prefer this tool over define_row_set or apply_transformation, so usage is only implied.

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

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.

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

Annotations already declare non-readOnly, idempotent, non-destructive, closed-world. The description adds genuinely new behavioral context: this queues an asynchronous hosted job whose result must be fetched via get_job, the change is reversible and carries recorded provenance, and approval must be real. That exceeds what the annotations convey, though it doesn't cover failure modes or job lifetime.

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?

Three tight sentences, front-loaded with what the tool does, then the async/result-retrieval behavior, then the approval precondition. No filler; each sentence earns its place.

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 9-parameter mutation with no output schema, the description usefully routes the agent to get_job for results and states the approval requirement. However, with 22% parameter description coverage and no explanation of expectedRevision/idempotencyKey semantics, it is not complete enough for confident 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 only 22% across 9 required parameters, and the description clarifies only the approval/approval-fabrication aspect and the wave scope. Key parameters such as expectedRevision (concurrency control), idempotencyKey, runId, recipeId, and workspaceToken receive no added meaning in the description, so it fails to compensate for the coverage gap.

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 (apply), resource (transformation), and scope (one workspace wave), and adds distinguishing qualifiers 'approved' and 'reversible provenance' that separate it from propose_transformation and review_transformation. An agent can tell what it does without opening the schema.

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?

Explicitly states the precondition ('obtain actual user approval before calling'), names the follow-up tool for retrieving results ('use get_job'), and warns against fabrication. That is clear when-to-use, how-to-continue, and what-not-to-do guidance.

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

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

Annotations declare idempotentHint=true and readOnlyHint=false, and the description usefully adds that the call is asynchronous (queues a hosted job) with results fetched via get_job — behavior not derivable from the structured fields. It does not state permissions or failure modes, but it materially improves the agent's mental model.

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?

Two short sentences, zero filler, with the async behavior front-loaded. Every clause earns its place.

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 six-parameter, non-idempotent-looking job-queuing tool with no output schema and low parameter coverage, the description is thin — it explains the async handoff but omits wave compatibility requirements, what the job compares, and how to interpret results.

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 33% and the description adds nothing about the six required parameters. Concepts like fromWaveId/toWaveId are only obliquely implied by 'across project waves', and tableId/projectId are unexplained; the description fails to compensate for the coverage gap.

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 (compare) and resource (tables across project waves) with a qualifier ('compatible') that constrains scope. It does not name or differentiate against any sibling, but the purpose is unambiguous.

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 async workflow by saying it queues a hosted job and points to get_job for the result, which is real operational guidance. However, it gives no criteria for when to use this vs. siblings like run_table or render_project_table, nor any prerequisite (e.g. waves must be compatible).

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

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

The description adds real value beyond annotations: it discloses that the operation is asynchronous ('Queues a hosted job') and that despite readOnlyHint=false it does 'not mutate the project,' resolving the apparent tension in the annotation set. The 'revision-bound' framing also supports the idempotentHint by implying the expectedRevision pins the result. It stops short of covering permission requirements or failure modes.

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?

Two sentences, front-loaded with the core purpose and then the async-retrieval mechanic, with no filler. The jargon ('portable revision-bound document') is dense but each clause carries distinct information.

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 create tool with no output schema, the description correctly explains the job-queue pattern and result retrieval via get_job, and reassures on non-mutation. Gaps remain: no mention of validation/prerequisite ordering relative to validate_analysis_plan or run_analysis_plan, and the majority of parameters are semantically unexplained.

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 29%, so the description must compensate, yet it explains only two of seven parameters implicitly ('explicitly selected saved tables' for tableIds, 'revision-bound' for expectedRevision). Required-vs-optional distinctions, and the meaning of name, waveId, and projectId, remain undocumented in both places.

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+resource ('Create a portable revision-bound document') scoped to 'explicitly selected saved tables,' which clearly distinguishes it from run_analysis_plan and validate_analysis_plan by action. It does not name those siblings explicitly, so the differentiation is inferable rather than stated.

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 use condition ('for explicitly selected saved tables') and a follow-up step ('use get_job to retrieve its result'), which is useful implied guidance. However it never says when to prefer validate_analysis_plan or run_analysis_plan, nor any prerequisites (e.g. needing a validated plan first), so alternatives are left to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false. The description adds genuinely new behavioral context beyond them by disclosing that the operation is asynchronous (a queued hosted job) and requires get_job to retrieve the result.

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?

Two short sentences, zero filler, with the core purpose front-loaded and the async follow-up instruction immediately after. Every clause earns its place.

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 no-output-schema async mutation tool, the description covers the key operational fact (job queueing plus get_job). It could mention the workspace token requirement or that the project is created within a workspace, but nothing essential to invoking it correctly is missing.

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 50%; requestId and workspaceToken are documented in-schema, but name and idempotencyKey are not. The description supplies no parameter meaning at all, so it fails to compensate for the gap, sitting below the baseline-3 case.

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 plus a distinguishing qualifier: 'empty, versioned research project', which separates it from import_project (which brings in existing content). It does not explicitly name sibling alternatives, so it falls short of a 5.

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?

Gives clear operational context: the call queues a hosted job and the result must be fetched via get_job, which routes the agent to the correct follow-up tool. It stops short of stating when to prefer this over import_project or create_workspace.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false) but not the operational consequences. The description adds meaningful context beyond them: uploads leave the device, and the secret token is the sole credential and is unrecoverable. That credential-loss warning is a genuine behavioral disclosure.

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?

Three short sentences, front-loaded with the core action. The middle sentence is arguably process instruction for the agent rather than tool description, but it still earns its place by establishing the consent prerequisite.

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 a single-parameter schema, no output schema and clear annotations, the description supplies what is missing: the consent precondition, the data egress warning, and the irrecoverable credential. Only minor gaps remain, such as what identifier the caller receives back.

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?

One parameter at 0% schema description coverage; the schema only shows consentToUpload is a boolean const true. The description compensates partly by stating consent must be obtained, implying the flag's meaning, but it does not explain the const/true constraint explicitly.

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 (Create) and resource (workspace) with distinguishing qualifiers: private, temporary, no sign-in. This differentiates it from create_project, though it does not explicitly name that sibling.

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?

Usage is implied by 'without signing in' and the consent workflow, but the description never says when to choose this tool over create_project or when a workspace is appropriate versus a project. No exclusions or alternative routing are given.

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

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

Annotations already cover the safety profile (write, idempotent, non-destructive, closed-world). The description adds behavior beyond that: the write is an upsert ('create or replace') and is asynchronous ('queues a hosted job') with a defined retrieval path via get_job. This materially changes how an agent must call and follow up on the tool.

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?

Two sentences, front-loaded with the purpose and followed by the async workflow note. Every clause earns its place with no 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?

Covers the important async job semantics and the get_job follow-up, which are the hardest parts to infer. However, with 7 required parameters, nested objects, low schema coverage, and no output schema, the description leaves expectedRevision, idempotency, and the definition shape entirely undocumented.

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 29% across 7 required parameters, including a nested definition object, so the description carries a heavy burden. It mentions none of them: tableIds, projectId, expectedRevision, idempotencyKey, or workspaceToken are left entirely to the schema. 'Multilevel' only faintly hints at the levels structure.

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 ('Create or replace a reusable multilevel banner') with the qualifier 'multilevel' and 'reusable'. It is distinguishable from table-oriented siblings like run_table or render_crosstab, though it does not explicitly contrast with similarly named define_* tools.

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?

Gives clear operational context for the async flow: 'Queues a hosted job; use get_job to retrieve its result,' which routes the agent to the correct follow-up tool. It does not state when to prefer this over alternatives such as apply_filter or define_row_set, so no exclusions.

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

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

Annotations declare idempotentHint=true and non-destructive, and the description adds context beyond them by disclosing that the operation is asynchronous ('Queues a hosted job') and how to retrieve results via get_job. It stops short of explaining what 'replace' overwrites or how expectedRevision conflicts are handled.

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?

Two compact sentences with the core upsert purpose front-loaded and the async retrieval note second. No wasted clauses, though the phrasing 'with an optional cases-or-responses denominator for one detected multi-select question' is dense.

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 that queues a job with no output schema and a nested definition object, the description covers the async lifecycle pointer but omits revision-conflict behavior and the meaning of the replace semantics. Adequate but with clear gaps given the tool's complexity.

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 38% across 8 parameters (7 required). The description clarifies the semantically tricky 'multipleResponseDenominator' (cases-or-responses for a single detected multi-select question) but says nothing about projectId, expectedRevision, idempotencyKey, or workspaceToken, leaving the concurrency and auth semantics to the schema.

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 ('Create or replace a reusable ordered row-variable set') and scopes it with the optional denominator purpose. It is distinguishable from siblings like define_banner or define_survey_design, though it does not explicitly name those alternatives.

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?

'Queues a hosted job; use get_job to retrieve its result' gives a concrete follow-up routing step, which is genuinely useful. However, it gives no guidance on when to choose this tool over siblings such as define_banner, nor any prerequisites or when-not-to-use conditions.

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

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

Goes well beyond annotations by disclosing that the operation is asynchronous ('Queues a hosted job'), that the resulting design is immutable, that writes are atomic across tables, and that a real human approval is mandatory. Annotations only cover the safety profile (readOnly=false, idempotent=true, destructive=false); the async/approval semantics are new information that materially changes how an agent must call this.

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?

Three sentences, all front-loaded: what it creates, how results are retrieved, and the approval prerequisite. No filler; each clause adds actionable information.

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 complex nested-object mutation without an output schema, it covers the essentials an agent needs: async job handling, approval requirement, and atomic multi-table scope. Missing are revision-conflict behavior, permission expectations, and any error/failure semantics, which leaves minor gaps.

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 25% (just requestId and workspaceToken), so the description carries most of the burden for 8 required params, including nested definition and approval objects. It hints at approval authenticity and table selection but says nothing about expectedRevision conflicts, idempotencyKey semantics, or the meaning of definition fields such as fpcMode/lonelyPsuPolicy, leaving most parameters unexplained.

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 ('Create an approved immutable Taylor or replicate-weight survey design'), plus the alternate path ('or assign an identical existing design'). The 'atomically across selected tables' scope and the Taylor/replicate-weight qualifier distinguish it from siblings like set_weight or run_complex_survey_method.

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?

Gives clear operational context: 'Queues a hosted job; use get_job to retrieve its result' and the prerequisite 'Obtain actual user approval before calling.' It does not name alternative tools for related weighting/design tasks (e.g., set_weight), so it falls short of explicit alternatives, but the when-to-use condition is stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral facts beyond the annotations: exactly which data classes are destroyed and that the workspace token is revoked, plus 'permanently' signalling irreversibility.

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?

Two tight sentences with the destructive scope front-loaded and zero filler. Every clause carries information.

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 destructive mutation with strong annotation coverage and no output schema, the description covers impact and token revocation adequately. It falls short only on the required confirmDelete guard and on any permission/auth requirement.

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 50%, and the undocumented parameter is the critical one: confirmDelete (required, const true) is never mentioned in the description, so the agent gets no explanation of the confirmation guard. workspaceToken is well documented in the schema, so the description adds nothing there.

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 ('Permanently delete') plus resource ('the temporary workspace') and even quantifies the blast radius (project, file and job data). An agent can distinguish this from create_workspace/get_workspace purely from the description.

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?

No when-to-use guidance, no prerequisites, no alternatives named. Nothing tells the agent when deletion is warranted versus, say, exporting or inspecting the workspace first, nor that the token must be obtained from create_workspace.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description clarifies that the job itself does not mutate project state and that it is asynchronous. The 'without mutation' wording sits in mild tension with readOnlyHint=false, but it reads as job-creation being the only side effect rather than a genuine 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?

Two short sentences: the first states the read-only scope, the second the async retrieval path. Nothing is repeated from the schema or annotations and the important constraint is front-loaded.

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 no-output-schema async job, the description covers the essential contract: it is read-only w.r.t. project data, it is queued, and get_job returns the result. It omits any hint about what the proposal contains or any required permissions, but the core invocation path is complete.

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?

Five parameters at 60% schema coverage with no mention of any parameter in the description. The renames object (the natural input to a drift-repair proposal) and requestId's idempotency semantics are left entirely to the schema, so the description does little to compensate for the coverage gap.

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 action (inspect wave compatibility / detect schema drift) and adds the crucial qualifier that it only proposes repairs rather than applying them, which separates it from the sibling repair_schema. It does not name that sibling explicitly, so the differentiation is inferable rather than stated.

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?

Gives the operational context that this queues a hosted job and that the result must be fetched via get_job, which is essential guidance for an async tool. It stops short of stating when to run detection versus repair_schema or inspect_project, so the alternative-selection rule is only implied.

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

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

Annotations already declare the write/idempotent/non-destructive profile, so the bar is lower, and the description still adds meaningful behaviour: definition-only by default, full data only when explicitly requested, and asynchronous queue-and-poll execution. It stops short of saying where the package lands or how long the job persists.

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?

Two sentences, no filler, and the primary behaviour and the default are front-loaded before the async follow-up. Every clause carries information the agent needs.

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, the description correctly redirects the agent to get_job for results and discloses the asynchronous job model, which is the key missing piece an agent would otherwise guess at. Minor gaps remain around the fate of the temporary workspace and package retention, but nothing essential to a correct call is absent.

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 50% (projectId and dataPolicy are undescribed), so the description has to compensate. It does so for the ambiguous parameter: the phrase 'definition-only package by default or an explicit full-data package' gives concrete meaning to the omitted/included dataPolicy enum and its default, which the schema alone leaves opaque.

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 (export a project package) plus the two output variants it supports, which immediately separates it from import_project and the analyser/renderer siblings. It does not, however, name an alternative sibling (e.g. get_download_link) by name, so an agent gets the purpose but not the routing.

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?

Gives an explicit follow-up instruction: the call queues a hosted job, and get_job is named as the way to retrieve the result. That is real when-to-use guidance for the async pattern, but there is no guidance on when to prefer full-data export, or how this differs from import_project / get_download_link.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description's phrase 'one fixed ... record' modestly reinforces single, stable retrieval beyond what annotations state, but adds little about error behavior or lookup failures.

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?

A single front-loaded sentence with no filler. It is efficiently sized, though its brevity borders on under-specification given the opaque resource name.

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?

An output schema exists so return values needn't be explained, and annotations cover the safety profile. However, with an undefined domain term and an undocumented identifier parameter, the definition is only barely sufficient for an agent to invoke it confidently.

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% and there is one required parameter, so the description must compensate. 'By identifier' only minimally identifies the id's role; it gives no format, provenance, or constraints (maxLength 160 is schema-only) for the value the agent must supply.

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 names a specific verb ('Fetch') and a precise resource ('one fixed Crosstabs evidence record') with the lookup key ('by identifier'). It distinguishes itself implicitly from search/listing siblings by emphasizing single-record retrieval, but never names an alternative tool. The domain term 'fixed Crosstabs evidence record' is jargon-heavy and not defined.

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?

There is no guidance on when to use this versus siblings like 'search' or the other get_* tools. It never states where an identifier comes from, nor any preconditions for calling it.

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

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

Annotations already declare the safe-mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds genuinely new behavior: this is asynchronous, it only queues a hosted job, and the result must be fetched with get_job rather than returned inline — a fact not derivable from the annotations or schema.

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?

Two short sentences, zero filler, with the async-job follow-up placed immediately after the purpose so the agent learns the critical workflow detail up front.

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 9-parameter, 6-required job-submission tool with no output schema and low schema coverage, the description is minimal. It correctly frames the async pattern but leaves most parameters and the distinction from refresh_report_pack unexplained.

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 22% (just requestId and workspaceToken), leaving projectId, expectedRevision, idempotencyKey, waveId, tableIds and templateId undocumented anywhere. The description mentions only the format choices ('PPTX or DOCX'), which the enum already conveys, so it does not compensate for the gap.

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 plus the output artifact types ('editable evidence-linked PPTX or DOCX pack'), which is concrete and distinguishable from generic report tools. It does not, however, distinguish itself from the close sibling refresh_report_pack, so an agent must guess which of the two to use when a pack already exists.

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 gives a workflow cue — 'Queues a hosted job; use get_job to retrieve its result' — which tells the agent what to do after calling. It offers no guidance on when to prefer this over refresh_report_pack, no prerequisites, and no note that the required workspaceToken/idempotencyKey must be obtained elsewhere.

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

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

Annotations declare idempotentHint=true and readOnlyHint=false, but not WHY the tool isn't read-only. The description explains that: it queues a hosted job, which reconciles the non-read-only hint with the 'return events' phrasing. It also discloses append-only pagination semantics. It omits job lifetime/TTL and rate limits, so not 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?

Two sentences, zero filler, with the return shape front-loaded and the required follow-up call second. Every clause earns its place.

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, the description correctly identifies the payload (audit events) and how to obtain it (get_job). It leaves pagination mechanics (how to page with afterSequence/limit) to the schema, which is reasonable, but the async return path could be slightly more explicit.

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 40%, so the description must carry more weight. It implies pagination (limit/afterSequence) and states append-only ordering, which helps orient the cursor parameter. But it says nothing about projectId, afterSequence semantics, or the requestId retry contract beyond what the schema already documents.

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 names a specific verb+resource: returning paginated, append-only project audit events. That is concrete and distinguishable from siblings like get_job or inspect_project. It stops short of explicitly contrasting itself with other read/inspection tools, so it lands at 4 rather than 5.

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 actionable routing guidance for the follow-up step ('use get_job to retrieve its result'), which is the critical usage detail for an async job tool. It does not state when to prefer this over other audit/project inspection siblings, but the workflow instruction is clear.

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

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

Annotations already declare the safe read/idempotent profile, so the bar is lower. The description usefully adds that the link contains a secret in its fragment and must not be shared publicly, which is genuine behavioral context not present in annotations. It doesn't mention expiration or link lifetime, keeping it below 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?

Two tight sentences, front-loaded with the action and followed by the critical security constraint. Every sentence earns its place with no 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?

For a low-complexity 2-parameter tool with annotations covering safety and no output schema, the description covers purpose, scope, and the key security caveat. It does not explain the returned link's form or lifetime, which is a minor gap but not disqualifying.

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 50%: workspaceToken is well-documented in the schema, but fileId has no description in either schema or description. The description doesn't compensate for the undocumented fileId or explain accepted file/artifact identifiers, so the baseline 3 holds.

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 (Create) and resource (a private browser download link) and scopes it to uploaded files or generated artifacts in this workspace. An agent can immediately tell what the tool produces. It doesn't differentiate from siblings like fetch or get_rendered_table, but the resource is unambiguous.

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?

Usage is implied by the phrase 'for an uploaded file or generated artifact in this workspace,' which scopes when the tool applies. However, no explicit when-to-use vs alternatives is given, and no sibling is named as the alternative for other cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered structurally. The description contributes by naming the content domains returned (privacy, retention, execution limits), but it does not describe the response format or the actual constraints themselves. With annotations carrying the behavioral burden, a 3 is appropriate.

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?

A single front-loaded sentence with no padding; the verb leads and the scope follows. The only minor cost is the dense compound phrase 'accountless hosted MCP' plus a four-item list, which reads as slightly compressed rather than polished.

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 zero-parameter, read-only informational tool with no output schema, the description covers what domains the response addresses. It stops short of saying how the information is structured or when the limits matter, but nothing essential for correct invocation is missing.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. Schema coverage is 100% with an empty properties object, consistent with a no-argument informational 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?

The description uses a specific verb ('Describe') and enumerates the resource scope: accountless hosted MCP capabilities, privacy, retention, and execution limits. That scope clearly separates it from the sibling survey-analysis tools, though the phrase 'accountless hosted MCP' is jargon that may not be self-evident to an agent.

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?

There is no explicit statement of when to call this tool versus alternatives, nor any prerequisite or trigger condition. The usage is only weakly implied (call it to learn about limits), so an agent must infer the context entirely on its own.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds valuable behavioral context: polling timing, result availability tied to job status, and error handling for failed jobs. It doesn't mention authentication explicitly (though workspaceToken is described in schema) or rate limits beyond polling interval.

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 three sentences that are front-loaded and every sentence carries essential information without waste. It's appropriately sized and structure is clear.

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 read-only polling tool with no output schema, the description covers the core behaviors: what it does, when to poll, result states, and alternative tools for specific outcomes. It could mention authentication requirements (workspaceToken) or error formats, but annotations cover safety and the schema describes the token. Overall, it's sufficiently complete 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 coverage is 50%: workspaceToken has a description, jobId does not. The description does not add parameter meaning beyond what the schema provides. Baseline 3 is appropriate given the partial coverage and no added detail in the description.

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 clearly states the specific action: 'Read a queued analysis job.' It distinguishes itself from other read tools by specifying a job-based operation, but it doesn't explicitly contrast with all siblings (though it does direct to get_download_link and get_rendered_table).

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 provides clear usage context: wait at least two seconds between polls, only succeeded jobs have completed results, failed jobs contain errors. It explicitly names alternative tools for specific cases: get_download_link for artifact IDs and get_rendered_table for render_project_table jobs. It lacks explicit 'when not to use' beyond the tool routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds one genuine behavioral fact beyond them — that respondent rows are never included — but says nothing about error behavior for non-succeeded jobs or the shape of the rendered widget.

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?

Two tight sentences, front-loaded with the operation and scope. Every clause earns its place, including the respondent-row exclusion.

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, the description carries the burden of describing the return value; it partially does so (aggregate result rendered as a widget, respondents excluded) but omits format and completion/failure semantics. Adequate but with clear gaps for a render step.

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 50%; workspaceToken is fully documented in the schema (secret capability, never in query string) and jobId is a self-evident UUID. The description clarifies that jobId refers to a render_project_table job, which adds marginal meaning, but does not document jobId's provenance or any constraints beyond the schema.

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 (render) and resource (canonical aggregate result) and ties it to the output of a succeeded render_project_table job, which usefully distinguishes it from the sibling that creates the job. It does not, however, explicitly contrast itself with other render_* or get_job siblings.

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 'succeeded render_project_table job' implies a prerequisite and a lifecycle position, so usage is inferable. But there is no explicit when-to-use/when-not guidance and no named alternative (get_job, render_table, render_crosstab), leaving the agent to infer the routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds that the resource limits are "fixed" (i.e., not configurable here), which is a small extra signal, but says nothing about what is returned, whether the runtime is the local or remote one, or any auth requirement.

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?

A single ten-word sentence with the action and the scope front-loaded and no filler. Nothing in it is redundant.

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 zero-parameter read-only tool this is nearly sufficient, but there is no output schema, so the description is the only place that could tell an agent what "inspect" actually returns (status fields? limits? capabilities?). That gap, plus the vague antecedent of "this hosted runtime," keeps it at minimum-viable rather than complete.

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 tool takes zero parameters, so there is nothing to document and the schema-level baseline of 4 applies. The description adds no parameter information, which 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 pairs a concrete verb ("Inspect") with a specific resource ("this hosted runtime and its fixed resource limits"), so an agent can tell it is a diagnostic/introspection tool rather than an analysis tool. It does not explicitly contrast itself with siblings like get_headless_capabilities or get_job, but the resource is distinct enough to be recognizable.

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?

There is no statement of when to call this tool, what triggers a need to inspect the runtime, or which siblings (e.g. get_headless_capabilities) cover overlapping territory. The agent must infer the use case entirely from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond that: the response includes a private upload link, which signals sensitive output content the agent should handle carefully.

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?

Two short sentences with zero filler; the content enumeration is front-loaded and the sensitive-output note follows. Nothing to trim.

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?

There is no output schema, so the description carries the burden of describing the return value, and it does so explicitly (files, recent jobs, expiry, upload link). Safety behavior is covered by annotations. Only the absence of any alternative-tool routing keeps it short of complete.

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 100% and the workspaceToken description is unusually rich (secret capability, treat as a password, never in a query string). The tool description adds nothing about the parameter, so the baseline 3 applies when the schema does all the work.

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 (List) and resource (this temporary workspace) and enumerates exactly what is returned: files, recent jobs, expiry, and a private upload link. An agent can distinguish it from create_workspace/delete_workspace, though the description never names those siblings explicitly.

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?

Usage is implied by possession of a workspaceToken and by the word 'temporary', but there is no explicit when-to-use or when-not-to-use guidance and no routing to alternatives such as get_job or get_download_link. Adequate but leaves the agent to infer the trigger condition.

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

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

Annotations cover the safety profile (readOnly=false, idempotentHint=true, destructiveHint=false), and the description adds the important asynchronous behavior beyond that: a job is queued and must be polled via get_job. It does not say what happens on validation failure, whether a partial import can occur, or how validation errors surface.

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?

Two short sentences, zero filler, with the operation and its follow-up action front-loaded. Every sentence earns its place.

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?

There is no output schema, and the description reasonably covers retrieval of results via get_job, so the return path is handled. However, for a 6-required-parameter mutation tool, the semantics of expectedRevision and idempotencyKey and the failure behavior of validation are left undocumented.

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 description mentions no parameters at all, and schema coverage is only 50% — uploadId, requestId, and workspaceToken are documented in the schema, but projectId, idempotencyKey, and expectedRevision (apparently an optimistic-concurrency revision guard) are unexplained in both places. With a mutation tool carrying an expectedRevision and idempotencyKey, the description should have compensated for that gap and did not.

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-plus-resource ('Validate and import respondent records into a project wave'), which is clear on its own. It does not explicitly distinguish itself from close siblings such as import_project or replace_dataset, so the agent must infer the boundary from names alone.

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?

Gives a concrete next-step routing rule: the call queues a hosted job and the agent should call get_job for the result. That is genuine usage guidance, but there is no statement of when not to use this tool versus import_project/replace_dataset.

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

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

The annotations already declare idlempotentHint=true, readOnlyHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious async behavior — that this queues a hosted job rather than returning inline — which is exactly the kind of trait annotations cannot express.

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?

Two sentences, zero filler, and the primary action is front-loaded ahead of the async note. Every clause earns its place.

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 mutating, job-queuing tool with no output schema, the description covers the essentials: what it produces and how the result is retrieved via get_job. Only the undocumented idempotencyKey and the lack of sibling-selection guidance leave minor gaps.

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 75%, so most parameters (uploadId, requestId, workspaceToken) are documented in the schema itself and the description adds nothing beyond them. The one uncovered parameter, idempotencyKey, is left undocumented in both the schema and the description, so baseline 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?

States a specific verb (import) and resource (a full-data Crosstabs project package) plus the outcome (as a new workspace copy), which distinguishes it implicitly from import_dataset and create_project. It is clear and actionable without needing to open the schema.

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 one explicit routing cue — 'use get_job to retrieve its result' — which sets up the async workflow correctly. However, it never says when to choose this over siblings like import_dataset, create_project, or create_workspace, so the selection guidance is only partially covered.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, and the description explains the non-obvious reason: the call queues a hosted asynchronous job rather than returning data directly. That resolves the apparent tension between a read-style 'inspect' and non-readOnlyHint, and 'redacted' signals sanitized content. It does not mention job lifetime, polling expectations, or permission requirements.

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?

Two sentences, no filler; the async-job consequence and the get_job follow-up are front-loaded right after the purpose statement.

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, no-output-schema tool the description supplies the two things an agent most needs: what is inspected and that the result arrives via get_job. Missing only secondary details such as return shape and any auth/permission caveats beyond workspaceToken in the schema.

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 67%; requestId and workspaceToken carry their own descriptions (UUID reuse rules, secret handling), so the schema does the heavy lifting. The description adds only the implied meaning of projectId via 'workspace project graph' and no format or syntax detail beyond the schema.

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 (inspect) and resource (redacted workspace project graph, capabilities, current revision), which is concrete and not a restatement of the name. It does not, however, distinguish itself from close siblings like get_workspace, get_runtime_status or list_projects, so an agent must guess which inspection tool to pick.

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?

Gives clear operational context: the call queues a hosted job and the result must be fetched with get_job — an explicit next-step alternative. It stops short of stating when to use this over get_workspace/list_projects or any exclusions, so it is strong but not complete routing guidance.

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

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

Annotations declare readOnlyHint=false and idempotentHint=true. The description adds key behavioral context beyond annotations: it queues a hosted job (async operation), and results must be retrieved via get_job. This is important context not captured in annotations. It doesn't describe rate limits or auth details, but the async disclosure is valuable.

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?

Two sentences, front-loaded with the purpose then the follow-up action. No wasted words.

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 read-only listing tool with no output schema, the description covers the essential async workflow and the retrieval path via get_job. It doesn't explain pagination (limit/cursor) or what 'redacted summaries' contain, but the core operation is understandable.

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 50%, so the schema documents two of four parameters (requestId, workspaceToken) while limit and cursor lack descriptions. The description doesn't add meaning for limit or cursor, but the async/job context implicitly explains the presence of requestId. Baseline 3 is appropriate given partial schema coverage and no additional param details in the description.

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 (List) and resource (redacted summaries from the workspace project store), which is clear. However, 'redacted summaries' is slightly ambiguous — it's not immediately obvious whether these are project summaries or summary statistics, and the description doesn't distinguish from sibling inspect_project or get_workspace.

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?

Explicitly explains the async pattern: 'Queues a hosted job; use get_job to retrieve its result.' This tells the agent when and how to follow up. It doesn't name when-not to use it versus inspect_project, but the queuing guidance is clear context.

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

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

Goes beyond the annotations by disclosing that respondent weights stay in a temporary hosted workspace (no persistence), that a revision-bound review fingerprint is produced, and that execution is asynchronous. Annotations already cover idempotency and non-destructiveness, so this contextual layer is genuinely additive rather than redundant.

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?

Three dense sentences, front-loaded with the purpose, followed by return content and the async/job pattern. Nothing is wasted, though the second sentence packs several diagnostics into a single clause.

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?

Compensates for the absent output schema by naming the returned diagnostics (aggregate balance, trimming, effective-base, review fingerprint), which is valuable. However, for a 10-parameter required-input tool at 20% schema coverage, the complete omission of parameter meaning leaves a substantial gap.

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 20% with 10 required parameters, so the description must carry the burden and largely does not. It alludes to 'population margins' (targets) and 'trimming' (trim) but never explains expectedRevision, tolerance, maxIterations, baseWeightId, or the workspaceToken/what-happens semantics.

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+resource ('Preview explicit population margins against the saved active wave') and clarifies that it is a non-mutating dry-run of raking, which implicitly separates it from apply_raking_weights. It does not name the sibling explicitly, so routing relies on the preview/apply verb contrast rather than an overt 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?

Gives clear operational context: it queues a hosted job and directs the agent to 'use get_job to retrieve its result,' which is a concrete alternative/callback path. It does not explicitly state when to prefer preview over apply_raking_weights, leaving that to inference from the verb.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, but the description adds the crucial asynchronous behavior: it queues a hosted job and results must be fetched with get_job. That execution model is not visible in the annotations and materially changes how an agent should use the tool. It stops short of explaining job lifecycle, timeouts, or failure behavior, so not 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?

Two tightly written sentences with no filler. The functional output is stated first and the retrieval instruction second, which is the right front-loading for an asynchronous tool.

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 three-parameter async job with no output schema, the description tells the agent both what is computed and how to collect the result via get_job, which is the key missing piece. It could go further by noting that repeated calls with the same requestId return the existing job (matching idempotentHint), but the essentials are present.

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 67% (requestId and workspaceToken documented in-schema), so the schema carries most of the burden. The description adds no parameter-level meaning, such as clarifying projectId scoping or the retry semantics of requestId, leaving it at the baseline level for medium coverage.

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 output ('Return bounded types, missingness and cardinality diagnostics'), which tells an agent exactly what the tool produces. It does not name or distinguish itself from sibling tools like inspect_project or detect_schema_drift, so a 4 rather than a 5.

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 follow-up workflow ('Queues a hosted job; use get_job to retrieve its result'), which is genuinely useful for invocation. However, it offers no guidance on when to choose profile_dataset over related diagnostics tools such as inspect_project or detect_schema_drift, nor any prerequisite context, so usage is only implied.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, so the safety profile is covered. The description adds genuinely new behavior: this queues a hosted (asynchronous) job and its result must be fetched via get_job, and that the recipe is data-free/draft. That async workflow disclosure is valuable context beyond the 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?

Two sentences, front-loaded with the core action and followed by the retrieval instruction. Every clause earns its place with no filler.

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 tool with six required parameters, deep nested objects, and no output schema, the description is thin. It omits the revision/idempotency contract, the structure of the transformation definition, and the full propose-then-review-then-apply lifecycle, so an agent cannot confidently construct a call from this text alone.

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 33% and the description says nothing about any of the six required parameters, including the complex nested 'definition' object, expectedRevision, projectId, or idempotencyKey. With low coverage the description should compensate but provides zero parameter meaning, so it falls below the baseline.

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 uses a specific verb+resource ("Create a draft... transformation recipe") and scopes it with "data-free" and "for later review," which distinguishes it from the sibling apply_transformation. It does not, however, name any sibling explicitly, so the differentiation is implied rather than stated.

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 signals the workflow (draft first, review later) and tells the agent to call get_job to retrieve the result, which is useful routing. But it never states when to pick this over apply_transformation, nor what triggers the subsequent apply step, leaving the core when-to-use decision to inference.

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

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

Annotations cover the safety profile (idempotentHint=true, destructiveHint=false, readOnlyHint=false), and the description adds genuinely new context: it queues an asynchronous hosted job, preserves manual regions, and requires real user approval. The anti-fabrication warning ('do not fabricate approval fields') is a valuable behavioral guardrail beyond structured data.

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?

Three tight sentences: what it does, how the async result is retrieved, and the approval prerequisite. The most important constraint is front-loaded and nothing is padding.

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?

Given a 9-parameter, nested-object mutation with no output schema, the description covers the async model and approval gate but omits the meaning of most required parameters (revision precondition, idempotency key, generation/upload IDs). Adequate but with clear gaps for a tool of this complexity.

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 33% across 9 parameters (8 required, nested approval object). The description only touches the approval fields obliquely ('do not fabricate approval fields') and says nothing about expectedRevision, generationId, idempotencyKey, or workspaceToken semantics, so it fails to compensate for the coverage gap.

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+resource ('refresh generated regions') and adds a scope qualifier ('while preserving declared manual regions') that meaningfully separates it from generate_report_pack. It never names the sibling explicitly, so it falls just 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?

Provides a clear prerequisite ('Obtain actual user approval before calling') and a follow-up route ('use get_job to retrieve its result'), which tells the agent how to complete the workflow. It stops short of stating when to prefer refresh over regenerate.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, which covers the safety profile. The description's 'deterministic' roughly restates idempotentHint and adds no new behavioral context (no auth requirements, no constraints on what it accepts beyond what the schema already enforces).

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?

A single front-loaded sentence with no filler. It is efficient, though the brevity is achieved partly by omitting necessary detail rather than by tight writing.

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 presence of an output schema relieves the description of explaining return values, but for an 8-parameter tool with 38% schema coverage and no usage or parameter guidance, the description is not complete enough for an agent to invoke it confidently. It also fails to differentiate itself from the many other render/analyze tools.

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 38% across 8 parameters, so the description carries a heavy burden and provides none of it. It never mentions the required integer-frequency matrix, the mandatory inputSemantics attestation, the percentage modes, or the label/variable parameters, leaving most parameters undocumented in prose.

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 names a verb ('Render') and a resource ('aggregate crosstab widget'), so the basic action is identifiable, but qualifiers like 'evidence-linked' and 'widget' are vague jargon rather than concrete scope. It does nothing to distinguish this from sibling renderers such as render_table, render_project_table, or the analyzer analyze_crosstab.

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?

There is no guidance on when to choose this tool over analyze_crosstab, render_table, or run_table, nor any stated prerequisite such as needing counts before rendering. The agent must infer usage entirely from the name.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely non-obvious behavior: this is asynchronous, it enqueues a hosted job, and the result must be fetched via get_job. It omits auth/permission requirements and how to handle a failed job, but the async contract is the key disclosure an agent needs.

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?

Two tight sentences with the primary action front-loaded and the follow-up routing placed second where it belongs. No wasted words, though the second sentence is compressed to the point of obscuring the parameter contract.

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 7-parameter write tool with no output schema and 29% parameter coverage, the description is too thin: it never explains the revision-binding semantics, the workspaceToken/evidenceId roles, or what the queued job ultimately returns. Only the async hand-off to get_job is covered, leaving most of the invocation contract undocumented.

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 29% (only requestId and workspaceToken are documented), so the description is expected to compensate and it does nothing — no mention of projectId, tableId, expectedRevision, evidenceId, or waveId. The revision/evidence pair is especially opaque and is left entirely unexplained.

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 (Render) and resource (project table), scoped as a 'revision-bound saved table execution,' which distinguishes it from render_crosstab and run_table. The phrase 'canonical workspace evidence widget' is internal jargon that adds no discriminating information, but the core purpose is clear.

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 usage via the async workflow ('Queues a hosted job; use get_job to retrieve its result'), which routes the agent correctly to a sibling for the result. However, it never states when to prefer this over render_crosstab, run_table, or run_tab_book — the closest alternatives — so selection depends on inference.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds genuinely non-structured context: the operation is asynchronous and queued as a hosted job, results are retrieved via get_job, the plan must be pre-approved by a real user, and approval fields must not be fabricated. Those are meaningful behavioral details beyond what the 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?

Three short sentences, all front-loaded: the action, the async job model, and the approval guardrail. No filler, and the most important constraint (approval) is placed where the agent will read it.

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 16-parameter, 11-required mutation tool with no output schema, the description usefully covers the async job model and result retrieval path. However, it leaves the large semantic surface of the required parameters (plan, wave, revision, idempotency, workspace token) unexplained, so it is only partially sufficient.

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 19% across 16 parameters, and the description compensates for almost none of it. It gestures at the approval requirement but never explains planId, waveId, expectedRevision, idempotencyKey, renames, labelAliases, valueRecodes, categoryOrders, or typeConversions, leaving most of the input surface undocumented.

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 gives a specific verb and resource ("Apply an approved, reversible schema repair plan") and states the reversibility/approval posture, which cleanly separates it from read-only siblings. It does not explicitly distinguish itself from adjacent mutation tools like apply_transformation or undo_change, so the sibling differentiation is partial rather than complete.

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 states the key precondition ("Obtain actual user approval before calling") and the follow-up step ("use get_job to retrieve its result"), which is concrete usage guidance. It stops short of naming when NOT to use it or which sibling produces the plan to apply, so it is clear context without explicit alternatives.

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

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

With annotations already declaring readOnlyHint=false, idempotentHint=true and destructiveHint=false, the description adds genuinely non-redundant context: it is asynchronous (queues a hosted job, result via get_job) and, critically, it is gated on real user approval with an explicit warning not to fabricate approval fields. That approval/auth requirement and the async model are not derivable from the 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?

Three short sentences, front-loaded with the core action and constraint, then the async behavior, then the approval gate. No filler sentences and every clause carries actionable information.

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 10-parameter, nested-object mutation with no output schema, the description omits explanations of the concurrency guard (expectedRevision), the retry contract (idempotencyKey/requestId) and the renames mapping. The approval and get_job notes are covered, but the parameter surface an agent must populate is largely unaddressed.

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 30% (uploadId, requestId, workspaceToken documented), leaving 7 of 10 parameters undescribed in both schema and description. The description mentions 'approval fields' only, adding nothing about expectedRevision (optimistic concurrency), idempotencyKey, renames, waveId or label, so it fails to compensate for the low coverage.

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 ('Import a replacement wave') and adds a meaningful constraint ('without overwriting prior source data') that distinguishes it conceptually from import_dataset. It stops short of naming the sibling it competes with, so an agent must infer that distinction.

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?

Gives useful procedural guidance ('Queues a hosted job; use get_job to retrieve its result') and a precondition ('obtain actual user approval before calling'). However it never states when to choose replace_dataset over import_dataset, or what distinguishes a 'replacement wave' from a new import, which is the central routing decision here.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely non-redundant behavior: the call is asynchronous (queues a hosted job), the result must be fetched via get_job, and human approval must be real rather than fabricated. It stops short of describing state effects on the recipe (e.g., whether approval is reversible).

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?

Three short sentences, front-loaded with the action and purpose, then the async pattern, then the approval warning. Slight overlap between 'with recorded human approval' and 'do not fabricate approval fields', but nothing is wasted.

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?

Covers the async job pattern and the human-approval prerequisite, which are the highest-risk behaviors for a 9-parameter, all-required mutation tool with no output schema. However, with low schema coverage it omits revision-conflict handling, idempotency semantics, and the effect of the decision on the recipe's lifecycle.

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 22% across 9 required parameters, so the description is expected to compensate, yet it only alludes to the approval object ('do not fabricate approval fields'). Key semantics such as expectedRevision (optimistic concurrency), idempotencyKey, workspaceToken, decision, and note are left entirely to bare schema types.

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 pair (approve/reject) and resource (draft transformation recipe) with the recorded-approval qualifier. An agent can distinguish it from propose_transformation, apply_transformation, and undo_transformation without opening schemas.

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?

Gives a clear precondition ('Obtain actual user approval before calling; do not fabricate approval fields') and names the follow-up path ('Queues a hosted job; use get_job to retrieve its result'). It does not explicitly contrast with apply_transformation or undo_transformation, but the approval-workflow context is unmistakable.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the mutation/idempotency profile is already covered. The description adds the key behavioral trait not in the annotations: the work is queued as a hosted job and results are fetched asynchronously via get_job. It does not state failure modes or what 'review findings' concretely contain.

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?

Two tight sentences, front-loaded with the core action and outcome, then the async retrieval note. No filler; every clause carries information.

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 tool with a very deep nested plan schema and no output schema, the description is thin. It does cover the two most uncertain things (async queueing and the rough return content), but says nothing about the plan structure it demands or how it relates to create/validate_analysis_plan.

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 50%: requestId and workspaceToken are documented in the schema, but projectId and the large nested plan object carry no field-level descriptions. The description adds only the loose notions 'portable plan' and 'loaded project revision', which maps to the plan/projectRevision concept but does not explain the plan's fingerprints, tables, or version constraints.

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 gives a specific compound verb (validate + execute) and a clear resource (a portable plan against one loaded project revision), plus the outcome (aggregate evidence and review findings). It does not explicitly name the closely related sibling validate_analysis_plan or create_analysis_plan, so the validate-vs-execute boundary must be inferred.

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 explicitly routes the agent to the follow-up tool: 'Queues a hosted job; use get_job to retrieve its result.' That is genuine usage guidance for the async workflow. It stops short of saying when to prefer this over validate_analysis_plan or what preconditions the plan must satisfy.

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

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

Annotations already declare it is non-readonly, idempotent, non-destructive, and closed-world. The description adds the async behavior ('queues a hosted job') and the retrieval path via get_job, which is real added value. It does not address the idempotency contract despite the idempotencyKey param, nor failure/timeout behavior.

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?

Two tight sentences with the primary action front-loaded and the retrieval step trailing. No filler or repetition. Slightly terse given the tool's complexity, but nothing is wasted.

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 17-parameter analytical job runner with no output schema, the description leaves most parameters and the result shape implicit. It covers the async retrieval lifecycle but not the model specification (outcome/predictors/design) an agent needs to invoke it correctly.

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 12% across 17 parameters, so the description must compensate and largely does not. It names the three method values (matching the enum) but explains nothing about outcome, predictors, clusters, missingPolicy, filterId, or surveyDesignId. Two undocumented parameters (workspaceToken, requestId) are the only schema-level descriptions.

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 ('Run') over a defined resource ('declared-design OLS, logistic, or K-means method') and notes the side effect of recording bounded canonical evidence. The three method names map cleanly to the enum, letting an agent distinguish it from generic siblings like run_analysis_plan. It stops short of explicitly contrasting itself with those siblings.

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 a genuine follow-up instruction ('use get_job to retrieve its result'), which is useful for an async tool. However, it gives no when-to-use vs alternatives (e.g., run_analysis_plan, run_table) and no prerequisites such as needing a prior declare_survey_design. Usage is implied, not stated.

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

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

Annotations already cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=false). The description adds valuable context beyond them: the operation is asynchronous (queues a hosted job), reports progress, supports cancellation, and its result must be fetched via get_job. It lacks detail on retry/error behavior, but idempotency is already declared.

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?

Two tight sentences with the operation front-loaded and the follow-up (get_job) placed last. No wasted wording, though it is terse to the point of omitting needed parameter context.

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-launch tool with no output schema, the description adequately covers the job lifecycle and result retrieval. But with 5 parameters at 40% schema coverage and no return-shape guidance, it leaves the agent under-informed about how to identify and parameterize the recipe to run.

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 40%, below the 50% threshold, so the description must compensate for the undocumented projectId, waveId, and tableIds. It mentions no parameters at all, leaving the meaning of the recipe selectors unexplained.

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: 'Compute the selected tab-book recipe.' It clearly conveys what is being produced (a tab book from a recipe with progress and cancellation), but does not distinguish itself from similar siblings such as run_table or run_analysis_plan.

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?

Gives real async-workflow guidance: 'Queues a hosted job; use get_job to retrieve its result,' which tells the agent the follow-up step. However, it offers no explicit when-to-use versus the other run_* siblings (run_table, run_analysis_plan, run_complex_survey_method).

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds genuinely new behavioral context beyond that: the call is asynchronous ('Queues a hosted job') and results must be retrieved separately via get_job. It does not clarify job lifetime, polling behavior, or what happens on duplicate requestIds, keeping it below 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?

Two compact sentences with the core action front-loaded and the follow-up (get_job) immediately after. No filler, though the second sentence could be folded into the first for maximum economy.

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 job-queueing mutation with no output schema, the description at least tells the agent where the result lands (get_job), which is essential. But it leaves three required parameters unexplained and never defines what 'diagnostics and evidence metadata' actually contains, so an agent lacks enough to invoke confidently on first try.

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 40% – requestId and workspaceToken are documented in the schema, while projectId, tableId, and waveId are not. The description adds no parameter meaning at all, not even clarifying that 'one crosstab' refers to the tableId or what waveId scopes. With low coverage, the description should compensate and does not.

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 ('Compute one crosstab') plus the added output ('diagnostics and evidence metadata'). The phrase 'one crosstab' hints at scope, but it never distinguishes itself from nearby siblings like render_crosstab, analyze_crosstab, or run_tab_book, so the agent must infer the difference.

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 a clear workflow directive: the tool queues a hosted job and the result is fetched via get_job. However, it gives no guidance on when to choose this over render_crosstab, analyze_crosstab, or run_tab_book, so usage relative to alternatives is only implied.

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

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

The annotations already declare read-only, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds only content scope and does not disclose any behavioral traits beyond the annotations, such as ranking, result limits, or query interpretation.

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, front-loaded sentence with no wasted words. It is appropriately sized for a simple search tool, though it could be slightly more informative without becoming verbose.

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?

An output schema exists, so return values need not be explained. However, for a one-parameter search tool with no schema documentation, the description should clarify the query input and usage context; it does neither, leaving significant gaps.

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% and the single required 'query' parameter is undocumented in both schema and description. The description does not explain what the query should contain, how it is matched, or any constraints beyond the schema's maxLength/minLength.

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 verb ('Discover') and resource ('Crosstabs methodology, limitations, and evidence pages'), making the tool's subject matter distinguishable from computational siblings like analyze_crosstab or render_crosstab. It does not explicitly differentiate itself from other search or documentation-related tools, but the purpose is understandable.

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?

There is no guidance on when to use this tool versus alternatives such as analyze_crosstab or fetch. The description implies it is for discovering methodology and evidence pages, but it gives no conditions, exclusions, or recommended scenarios.

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

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

Annotations mark this as non-destructive, idempotent, closed-world mutation. The description adds context annotations cannot: it queues a hosted job (async behavior), tells the agent to use get_job for the result, and mandates real user approval — a genuine auth/process constraint. It doesn't disclose what happens to existing weighting definitions or how expectedRevision conflicts are handled.

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?

Three short sentences, front-loaded with the core action, then the async behavior, then the approval constraint. No filler.

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?

Covers the mutation's async nature and approval requirement, which are the non-obvious parts of calling it. It leaves gaps — revision conflicts, the meaning of tableIds/definition — but with 8 required params and no output schema, what is present is the highest-value context. Adequate though not exhaustive.

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 25% with 8 required parameters, and the description names none of them. The approval precondition maps to the approval parameter, and the job mention maps to requestId, but the description adds no syntax or format detail beyond that. This is borderline given the low coverage but does not regress below baseline.

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+resource: 'Create and assign a validated weighting definition.' This distinguishes it from siblings like apply_raking_weights or preview_raking_weights, which apply/preview rather than create+assign a persisted weighting definition.

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 says to use get_job to retrieve the result, which implies async usage context, and gives a hard precondition (obtain actual user approval). But it doesn't state when to use this tool versus preview_raking_weights or apply_raking_weights, which is the more likely confusion given the sibling set.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond them by disclosing the asynchronous execution model (queues a hosted job) and the follow-up retrieval path via get_job.

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?

Two short sentences with zero filler, front-loading the core action and then the async follow-up. Every clause earns its place.

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?

There is no output schema, and the description correctly points to get_job for results, which covers the return path. However, for a 6-required-parameter mutation with only 33% schema coverage, the optimistic-concurrency semantics (expectedRevision) and the meaning of targetEventId remain entirely unaddressed.

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 33% (requestId and workspaceToken are documented), leaving projectId, expectedRevision, idempotencyKey, and targetEventId unexplained. The description adds no parameter meaning at all, so it fails to compensate for the coverage gap.

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 ("Reverse") and resource ("recorded reversible project mutation"), which is materially more precise than the tautological title. It does not, however, distinguish itself from the sibling undo_transformation, which an agent must choose between.

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 useful follow-up instruction ("use get_job to retrieve its result"), which is genuine operational guidance. But it offers no when-to-use criteria versus undo_transformation or any prerequisite/exclusion conditions.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower, and the description still adds the crucial non-obvious trait that this queues a hosted job rather than completing synchronously. It does not explain what happens on revision mismatch or how retries interact with idempotencyKey.

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?

Two sentences, zero filler, with the state change front-loaded and the async retrieval instruction second. Every clause earns its place.

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, 6-required-parameter mutation with no output schema and low schema coverage, the description covers the job-queue model but leaves the concurrency/idempotency contract and parameter meanings undocumented, so an agent could easily supply a stale revision or a reused key.

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 33% (2 of 6 params documented), so the description must compensate and does not: it never explains expectedRevision's optimistic-concurrency role, idempotencyKey's retry semantics, or projectId, and only alludes to runId via 'one applied transformation run'.

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 ('mark ... undone') and resource ('one applied transformation run') plus the side effect ('restore its derived variable'), so the agent knows exactly what changes. It does not, however, contrast itself with the sibling undo_change, which an agent must disambiguate against.

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 tells the agent the follow-up step ('use get_job to retrieve its result'), which is real operational guidance for an async tool. It gives no when-to-use versus undo_change, no prerequisites (workspace capability, revision), and no exclusions.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the description only needs to add context — and it does: the call queues an asynchronous hosted job rather than returning results inline, and it demands genuine human approval. This goes meaningfully beyond what the annotations convey, though it omits what happens on an expectedRevision mismatch or how retries interact with idempotencyKey.

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?

Three tight sentences, front-loaded with the operation and its scope, then the async behavior, then the approval gating. Every clause carries information and nothing is redundant.

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 10-parameter tool with a deeply nested metadata payload and no output schema, the description covers the async pattern, follow-up retrieval, and approval requirement well. But it never addresses the revision-concurrency contract implied by the required expectedRevision, nor the retry semantics of idempotencyKey/requestId, which are the highest-risk unknowns for an agent calling this.

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 20% across 10 required parameters, so the description must compensate — and it partially does by enumerating the metadata facets (label, value labels, missing values, measurement level, role, format) that map to the nested 'metadata' object and by referencing approval fields. However, expectedRevision, idempotencyKey, projectId, waveId, and variableName carry no explanation here or in the schema, leaving concurrency and scoping semantics opaque.

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 names a specific verb (apply/update) plus the exact resource and the set of metadata facets being changed (label, coding, missing-value, measurement, role, display-format). It also draws a sharp boundary — 'without rewriting respondent rows' — that separates it from data-mutating siblings like replace_dataset or apply_transformation. It stops short of explicitly naming a competing sibling such as propose_transformation or review_transformation, which keeps it at 4 rather than 5.

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 routes the agent to the correct follow-up tool for results ('use get_job to retrieve its result'). That is real when-to-use and what-next guidance, though there is no explicit when-not-to-use or sibling comparison against the proposal/review tools.

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

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

Annotations declare readOnlyHint=false and idempotentHint=true; the description adds the async behavior (queues a hosted job) and the follow-up retrieval path via get_job, which is genuinely useful context beyond the annotations. It does not contradict the destructiveHint=false or openWorldHint=false hints.

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?

Two sentences, front-loaded with the purpose and followed by the behavioral/workflow note. Minimal waste, though the job-queuing clause could be slightly tighter.

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 4-required-parameter async tool with a secret token and no output schema, the description covers the async pattern and result retrieval well. It stops short of clarifying the plan parameter format or the projectId's role, leaving a gap for a fairly complex 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 50%: requestId and workspaceToken are documented in-schema, but projectId and the complex 'plan' parameter are undocumented. The description calls it a 'portable analysis plan' but adds no meaning about the plan's structure or format, leaving the most opaque parameter unclarified.

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 (preflight/validate) and resource (portable analysis plan) plus the scope (against the current workspace project). An agent can distinguish it from run_analysis_plan and create_analysis_plan by the validation semantics, though the sibling names are not cited explicitly.

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 workflow guidance by naming get_job as the retrieval tool and implying preflight use before running. However, it never states when to choose validate vs run_analysis_plan or create_analysis_plan, so the routing decision is left to inference.

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