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

The description claims the tool is 'READ-ONLY' and 'It only reads — it never mutates state.' However, the annotation readOnlyHint is false, which directly contradicts this claim. This is a serious inconsistency that could mislead an agent into assuming safety when the annotation indicates otherwise. The description also fails to explain the openWorldHint implications.

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 relatively long but well-structured, front-loading the purpose and then detailing behavior, return type, mode, and a note. Every sentence adds value, though it could be slightly more concise. The structure is logical and easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the return structure (ComplexQueryResult fields), mode semantics, safety guarantees, and a runtime prerequisite. It is fairly complete for a complex analytical tool, though it could mention error behavior when the runtime flag is off. The absence of an output schema makes the return description essential, and it is adequately covered.

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 schema description coverage is 100%, so all parameters are documented in the schema. The description adds context about mode sync/async and examples of target_ref values, but these are also present in the schema. The description does not add significant meaning beyond the schema, so a 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?

The description clearly states the tool's purpose: asking a read-only Cortex analyst an operational question and getting a cited answer. It provides concrete example questions and distinguishes itself from siblings by emphasizing 'READ-ONLY' and 'complex_query'. The verb-resource pairing is explicit and 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 gives clear usage context with example questions and explicitly mentions a prerequisite (CORTEX_TOOL_RUNTIME_ENABLED flag). It does not explicitly state when not to use it or name alternative tools, but the scope is well implied and the examples make it evident this is for analytical queries.

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 and openWorldHint=true. The description adds concrete detail about the returned fields (ids, status, target, actor, criteria, timestamps, error) and emphasizes 'no artifacts', which goes beyond the annotation alone.

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 waste. The core purpose is front-loaded, and the alternative is given in the second sentence. Perfectly structured.

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 one-parameter read tool with annotations covering safety, the description explains the return projection and routes to the result-fetch sibling. It's complete enough for an agent to invoke correctly; could mention error handling but that's not critical here.

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% for job_id, so the schema fully explains the parameter. The description adds no extra semantics beyond that, so the 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 (Get) and resource (Cortex job's metadata and status), and explicitly clarifies it does not return artifacts. It also distinguishes itself from cortex_get_result, making its purpose unambiguous among 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?

Explicitly points to cortex_get_result as the alternative for fetching the structured result body, which is the main likely confusion. It doesn't discuss when to use this over cortex_list_jobs or other read tools, but the primary alternative is 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 already declare readOnlyHint and openWorldHint, but the description adds meaningful behavioral detail beyond them: the exact return shape, validation against per-kind schemas, and the privacy restriction on raw artifacts. This helps the agent understand what to expect and what is deliberately unavailable.

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 with no filler. The main purpose is front-loaded, the return shape is given immediately, and the raw-artifact caveat earns its place by managing expectations. Every sentence carries useful 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 single-parameter tool with no output schema, the description covers the essential contextual needs: return shape, accepted result kinds, and exclusion of raw artifacts. It could additionally explain status semantics (e.g., pending/failed states), but this is a minor gap given the explicit return shape and enumerations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents job_id with an example ('ctxjob_123'), and schema description coverage is 100%. The description does not add significant parameter-level semantics beyond mentioning job_id in the return shape. This meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Get a Cortex job's structured result.' It further distinguishes itself by stating what it returns and, importantly, what it does not return (raw artifacts), separating it from any raw-data or other Cortex job 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?

The description clearly communicates when to use this tool: when a structured result for a Cortex job is needed. It also gives an explicit limitation—raw artifacts are not returned—signaling when not to use it. However, it stops short of naming a specific alternative tool for retrieving raw artifacts, so it is not a full 5.

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, so the read-only nature is covered. The description adds value by stating raw prompt/model artifacts are NOT included and that it returns {runs: CortexJobRun[]}, which helps set expectations about output. However, it does not disclose any rate limits, pagination, or sort order, and the annotations already cover the safety profile.

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, each adding relevant details: the resource and scope, the read-only and exclusion note, and the return shape. It is efficiently written without fluff, though the third sentence about return shape could be considered slightly redundant given no output schema exists, but it is useful.

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 the tool is a read-only list with one parameter and no output schema, the description covers the key aspects: what it returns, what is excluded, and its read-only nature. There is no mention of pagination or ordering, but for a simple audit-trail list tool, this is adequate. The description is complete enough for an agent to call 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 coverage is 100% (job_id is fully described with format and example). The description does not add parameter-specific meaning beyond the schema, but it clarifies that the tool returns runs for that job, which is already implied by the schema. With full schema coverage, a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it lists attempt history (audit-trail runs) for a Cortex job, one row per execution attempt with status, model, metrics, timings, and errors. It clearly identifies the resource (Cortex job) and the action (list runs), but does not explicitly distinguish from sibling tools like cortex_get_job or cortex_list_jobs, relying on the term 'attempt history' to imply 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?

The description implies when to use it: to see attempt history for a specific job, and states what is not included (raw prompt/model artifacts). It does not explicitly state when NOT to use it or mention alternatives like cortex_get_job (which might return overall job status). The context of audit-trail runs is clear but exclusions are not.

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 say readOnlyHint=false and destructiveHint=false, but the description adds rich context: server-side actor resolution, ACL filtering before prompt construction, fails-closed behavior against cross-project leak, mode-dependent execution (embed vs enqueue), and idempotency semantics. These go well beyond the annotation flags.

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 dense paragraph with no filler. Every clause earns its place: the action, the endpoint, the preferred use cases, the mode behavior, the return shape, and the idempotency note. Information is front-loaded and the key differentiators appear early.

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 tool with no output schema, the description is remarkably complete. It explains the return object, how to poll async jobs, the ACL/security posture, and idempotency. Nothing an agent needs to call 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 100% and the description's parameter mentions (mode sync/async, idempotency_key dedupe, question recommendation) largely mirror the schema text. It adds no new semantics beyond what the schema already conveys, so the 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 action (launch a Cortex job) with an endpoint, identifies the governed launcher as the preferred path for specific job kinds (complex_query, divergence_error_tracking), and differentiates from siblings by name. An agent can immediately understand what it does and how it differs from cortex_run_job or cortex_get_job.

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 names the preferred use cases and explains sync vs async modes, pointing to cortex_get_result or cortex_job_runs for polling. It also notes idempotency behavior and the ACL-fails-closed design, giving clear when-to-use guidance without needing to inspect siblings.

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; the description adds useful behavioral context: return shape ({data: CortexJob[], next_cursor}), pagination mechanics, and the cross-project scope. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences front-load the core purpose, then give the essential return shape and pagination instruction. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers scope, ordering, filtering, mutability safety, return structure, and pagination continuation. An agent has everything needed to call and correctly page through this tool despite the lack of an output 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 75% and includes descriptions for kind, cursor, and status. The description reinforces the meaning of status/kind as filters and explains how cursor relates to next_cursor, adding practical usage context beyond the schema. Limit remains implicitly clear.

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'), resource ('Cortex jobs'), and scope ('across accessible projects'), plus ordering ('newest first'). This clearly distinguishes it from siblings like cortex_get_job (single job) and cortex_run_job (job creation/execution).

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 spells out when to use the tool: listing jobs with optional status/kind filtering and cursor-based pagination. It does not explicitly mention alternatives like cortex_get_job for single-job retrieval, but the purpose and scope are clear enough to guide selection.

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 and destructiveHint=false, so the agent knows this is a mutating but non-destructive operation. The description adds that the action re-queues the job for an additional attempt and returns a status, but does not disclose side effects like triggering execution, auth requirements, or error behavior. This is adequate but not rich.

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 sentence that packs the purpose, endpoint, and return value without wasted words. The key qualification ('failed or dead') is front-loaded and the response shape is included, making it highly scannable for an agent.

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 one-parameter tool with no output schema and minimal annotations, the description covers the operation, target resource, endpoint, and response format. Nothing an agent needs to decide whether to call this tool and what to expect 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 coverage is 100%, with job_id described as 'Cortex job ID to retry,' so the schema already carries the parameter meaning. The description reinforces this via the endpoint path (:id) but adds no new semantic details beyond the schema, matching 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?

States a specific verb ('Re-queue'), a clear resource ('failed or dead Cortex job'), and the mechanism ('one more attempt'). The endpoint and return shape are included, making the tool's function unambiguous and easily distinguishable from siblings like cortex_get_job or cortex_list_jobs.

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 clearly scopes usage to failed or dead jobs and frames the tool as a retry operation, which gives an agent the context needed to select it over run/get/list siblings. It does not explicitly state when not to use it or name alternatives, so it stops short of a full 5.

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 meaningful behavioral context beyond the annotations by warning that the result is a 'HYPOTHESIS, not fact' and naming the output fields: assumptions, evidence_refs, confidence, and uncertainty. This is valuable because annotations only say readOnlyHint=false, openWorldHint=true, destructiveHint=false. It does not disclose side effects like whether a run record is created, but the wrapper framing plus annotations make the operation's non-read-only nature reasonably clear.

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 tight sentences with no filler. Purpose is front-loaded in the first clause, the important hypothesis caveat follows immediately, and the final sentence flags the critical required parameter. 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?

The description provides a strong high-level mental model, including result semantics and the underlying job kind. However, for an 8-parameter tool with no output schema and three undocumented required fields, it leaves gaps: it does not explain what target_type/target_ref should be, whether the call is asynchronous or creates a persistent run, or how the result is delivered beyond the named fields. This is adequate but not fully self-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?

The description only says `question` is required, which the schema already encodes via `required` and `minLength`. It adds no semantic explanation for the other required parameters—`target_type`, `target_ref`, and `project_id`—which lack schema descriptions. With 63% schema description coverage, the description should compensate for at least the required undocumented fields, but it 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?

The description states a specific verb and resource: it 'estimates what MIGHT have happened under a hypothetical change' as a counterfactual_eval job. Naming itself a 'convenience wrapper around cortex_run_job' makes its relationship to the generic job tool explicit and distinguishes it from siblings like cortex_run_eval. This is not a tautology and gives an agent a clear, non-confusable purpose.

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 identifies when to use the tool: when job_kind='counterfactual_eval', and frames it as a convenience wrapper over cortex_run_job. This is useful selection guidance. However, it does not mention alternative tools such as cortex_run_eval or state explicit exclusion criteria, so it stops short of full when-not-to-use 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 already signal readOnlyHint=false (mutation possible) and openWorldHint=true, so no contradiction with the description. The description adds the useful fact that it returns the same job shape as cortex_run_job. However, it does not disclose actual side effects — running a workflow_eval may trigger LLM calls or create surface items (evidenced by options.create_surface_item) — which matters for a non-read-only operation.

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 dense sentences, front-loaded with the core purpose and the parent-tool relationship. No filler. It stops just short of 5 because it references 'same job shape' rather than describing it, keeping some semantic debt in the reader.

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 8-parameter tool with no output schema and 50% schema coverage, the description leaves too much implicit: what the returned job shape actually contains, what side effects occur, and how the criteria/target parameters fit together. Since it defers entirely to cortex_run_job's behavior without describing it, an agent cannot fully reason about invocation or 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 description coverage is 50% (options, criteria, input_refs, input_payload are documented; project_id, target_ref, target_type, question are not). The description adds zero parameter-level meaning, so it does not compensate for the undocumented half. For a wrapper tool it would help to explain how target_type, target_ref, and criteria interrelate, but none of that is present.

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: it wraps cortex_run_job for job_kind='workflow_eval' to check whether a run/case/workflow met its criteria (SLA, policy compliance, action-item ownership). It names the parent sibling explicitly, which differentiates it from cortex_run_job. However, it does not distinguish against other cortex_* siblings like cortex_launch or cortex_ask, so differentiation is partial.

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?

Implied usage is reasonably clear: use it to check whether a target met eval criteria, and it identifies cortex_run_job as the underlying tool. But it never states when to call cortex_run_job directly versus this wrapper, and offers no explicit exclusions or alternatives for the eval scenario.

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 goes well beyond the annotations by disclosing that the actor is resolved server-side from the API key, that the platform ACL-filters input_refs and target access before prompt construction, and that the return value is {job_id, status} plus an optional inline result when a synchronous runner completes. This is meaningful behavioral context for auth, access control, and async execution that the annotations do not provide.

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 dense and purposeful: the tool's core action is front-loaded, followed by actor resolution, ACL filtering, and return behavior. Every sentence earns its place, and there is no redundant repetition of schema content.

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 9 parameters, no output schema, and async behavior, the description covers the essential behavioral context: actor resolution, ACL filtering, and the return shape. It does not explicitly point to follow-up tools like cortex_get_job or cortex_get_result for asynchronous jobs, but the schema's rich per-parameter descriptions fill most practical 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 100%, so the baseline is 3 without any additional parameter explanation. The description adds a useful cross-cutting detail about input_refs and target access being ACL-filtered, but it does not meaningfully clarify individual parameters beyond what the schema already documents. This is adequate but not exceptional.

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 opens with a specific verb and resource: 'Enqueue a generic Cortex job.' It enumerates the job categories (evals, counterfactuals, experiments, attributions), so the agent can tell this is the umbrella runner rather than a specialized sibling. It does not explicitly name the specialized siblings like cortex_run_eval or cortex_run_counterfactual, so it stops 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?

The description says this is the 'generic' Cortex job runner but gives no explicit when-to-use versus alternatives, no exclusions, and no pointer to specialized helpers such as cortex_run_eval or cortex_run_counterfactual. The word 'generic' implies breadth, but the agent is left to infer when a specialized sibling would be a better fit.

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 indicate this is a mutation (readOnlyHint=false). The description adds a concrete behavioral requirement—the auth type needed (user-session JWT vs agent API key)—which is not captured in annotations. It does not contradict annotations, and the auth requirement is a meaningful extra behavioral detail for the agent to act on.

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 with no fluff. The core action is front-loaded, and the auth prerequisite is clearly stated as a secondary point. Every word earns its place; there is zero 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?

With no output schema, the description need not explain return values. All required parameters are documented in the schema, and the description covers the critical auth requirement and project scoping. It lacks mention of side effects like the agent appearing in a dashboard, but that's implied by 'visible in the dashboard' in the schema. Overall, the necessary call-time information is 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 coverage is 100%, so each parameter is already described. The description does not elaborate on parameter meanings beyond what the schema provides, though it does reiterate the project scope. The schema handles param semantics, so a baseline of 3 is appropriate; the description adds little beyond what the schema already states.

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'), a specific resource ('a new agent'), and a scoping condition ('inside one of the caller's projects'). It clearly differentiates from sibling agent tools like invariance_agent_list, invariance_agent_get, and invariance_agent_set_key, which handle other operations. 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 gives a clear prerequisite: requires a user-session JWT (not an agent API key), and points to the CLI to obtain one. It also implies the use case (creating an agent within a project) but does not explicitly compare to alternatives. It's helpful but lacks an explicit 'use this when' statement or exclusion of other agent 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 already declare readOnlyHint=true and openWorldHint=true, so the description's safety profile is covered. The description adds a useful behavioral detail: 'Requires a user-session JWT bearer', which informs authentication prerequisites beyond what annotations provide. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tightly worded sentence that front-loads the action and resource, then adds a crucial auth note. No redundancy; every word contributes value.

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?

This is a simple single-parameter, read-only tool with no output schema. The description covers the operation and auth requirement. While it does not explicitly state the return value shape, for a straightforward 'get by ID' operation, the given context plus annotations is sufficient for an agent to call 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 100%, and the schema already states 'Agent ID' for the id parameter. The description's phrase 'by ID' aligns with the schema but does not add any additional meaning (e.g., type, format, constraints) beyond what is already documented. Baseline of 3 is appropriate for high schema 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 uses a specific verb ('Fetch') and a specific resource ('a single agent by ID'), which clearly distinguishes this from sibling tools like invariance_agent_list (which lists agents) and invariance_agent_me (which fetches the current user's agent). The scope 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 the tool is for fetching a single agent by ID, but it does not explicitly state when to choose this over alternatives (e.g., 'Use agent_list to get all agents, use agent_me for the current user'). No exclusions or alternative routing is provided, so the guidance is implied rather than explicit.

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 and openWorldHint=true, covering the safety profile. The description adds a critical behavioral detail—'Requires a user-session JWT bearer'—which is not captured in annotations and is essential for successful invocation. This goes beyond the structured fields and adds real value.

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 sentence, concise and front-loaded with the action ('List agents'). It includes the scope and the auth requirement without any filler. 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?

For a simple listing tool with one parameter, the description is fairly complete. It specifies the scope, auth, and the fact it lists agents. It does not explicitly mention the return format (a list of agents) but that is implied by the verb. Given no output schema and the simplicity, the description is adequate, though it could mention any default behavior or lack of filtering.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers project_id with a description ('Project ID. The caller must be a member.'), so schema coverage is 100%. The description reinforces the project scope but does not add new syntax, format, or constraints beyond what the schema already provides. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List agents') and the scope ('inside one of the caller's projects'), which is a specific verb+resource pairing. It distinguishes itself from sibling agent tools (invariance_agent_me, invariance_agent_get, invariance_agent_create) by indicating this is a listing operation, not a single-item or mutation operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for enumerating agents within a project but does not explicitly mention when to use it over alternatives like invariance_agent_get or invariance_agent_me. There is no guidance on exclusions (e.g., 'for a single agent, use invariance_agent_get'). The context is clear for listing, but no explicit routing is provided.

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 readOnlyHint annotation already declares the non-mutating nature, and the description adds what the tool returns: the agent identity and API key. This disclosure is meaningful and consistent with the annotations, though it could add a note about the sensitive nature of the API key.

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, front-loaded sentences: the first gives the action and result, the second gives the practical reason to call the tool. No filler or redundant detail.

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 introspection tool with no output schema, the description covers both the result of invocation and the intended benefit. It stops short of spelling out the exact output shape, but nothing required 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 input schema is an empty object, meaning there are no parameters and 100% schema coverage. With zero parameters, the baseline of 4 applies, and there is simply nothing further for the description to explain.

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 action ('Show') and resource ('agent identity and API key') bound to the current credentials. This clearly distinguishes it from the many agent-related siblings such as invariance_agent_get and invariance_agent_list, which address other agents.

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 provides an explicit use case: confirming the agent context under which the MCP server operates. It does not reference alternative tools or exclusions, but the purpose of this parameterless introspection tool is unambiguous.

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 and destructiveHint=false, and the description adds the meaningful behavioral fact that every node written after setting the key must be signed with the matching private key. It also links the key to server-side verification during invariance_run_verify, providing context beyond the annotations without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with the primary purpose front-loaded and the key consequence following. Every sentence earns its place without unnecessary detail.

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 simple one-parameter tool, the description covers purpose, effect, and the verification context. Combined with fully documented schema and annotations, nothing needed to correctly invoke the tool 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 schema has 100% coverage with a full description of the public_key parameter, including format and length. The tool description adds no additional parameter-specific details, only the contextual purpose of the key, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Register or rotate') and a clear resource ('calling agent's Ed25519 public key'), which distinguishes it from sibling agent tools like invariance_agent_me and invariance_agent_create. It also adds the operational consequence of node-signing requirements, further clarifying its unique role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context that the key must be set before writing signed nodes, and explicitly references the verification step in invariance_run_verify, implying when this tool is needed. It does not explicitly state when not to use or compare alternatives, so it falls short of a full 5.

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 provide readOnlyHint and openWorldHint, so the safety profile is covered. The description adds useful behavioral context by specifying a turn-based session over runs/knowledge base, but it does not disclose how session state behaves, what max_turns does, or what kind of response the caller receives.

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 one front-loaded sentence that conveys purpose, target resource, and session behavior without redundancy. Every word contributes and nothing needs to be trimmed.

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 four parameters, no output schema, and no parameter documentation in the schema, the description is too sparse to be complete. It gives the gist but leaves callers guessing about optional parameter effects and response behavior.

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%, so the description must provide parameter meaning; it partially does by implying 'message' is the asked question and 'turn-based session' relates to session state. It does not explain model or max_turns, leaving two meaningful optional parameters effectively 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 clearly states that the tool asks a question against the agent's runs/knowledge base and is turn-based, which is far more specific than a tautology. However, it does not explicitly distinguish itself from similar-sounding siblings like cortex_ask, leaving some differentiation 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?

The phrase 'turn-based session' hints at multi-turn conversational usage, but there is no guidance about when to use this tool versus alternatives like cortex_ask, when not to use it, or what prerequisites might exist. Agents looking for routing guidance will not find it 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?

It discloses that creating a Capture does not require an execution upfront, that linking can be deferred, and that the tool returns the capture session. This is consistent with annotations readOnlyHint=false and destructiveHint=false, and no contradiction is present.

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, each with a clear job: define the resource, clarify the deferred-linking behavior, and state the return value. There is no filler or redundant repetition of schema details.

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 create tool with nine documented parameters and no output schema, the description provides adequate orientation: it defines what a Capture is, explains the relationship to run linking, and states the return type. It could more explicitly differentiate Capture from related session/case creation tools, but the essential invocation context is 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 100%, so the structured schema already documents all parameters thoroughly. The description adds context about deferred linking via invariance_capture_link but does not materially expand the meaning of individual parameters beyond what the schema already provides.

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 opens with a specific verb-resource pair ('Create a Capture') and defines the resource as a 'standalone evidence record (session, conversation, trace)'. The deferred-linking behavior ('link a capture to a run later with invariance_capture_link') clearly distinguishes this tool from run-creation and capture-linking 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 description communicates the key usage context: captures are for standalone evidence that can be linked to a run later, naming invariance_capture_link as the follow-up tool. It does not explicitly enumerate when-not-to-use cases or contrast with sibling tools like session_create, but the intended workflow 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 carry readOnlyHint=true, so the safe-read behavior is covered. The description adds useful domain context about captures being standalone and linkable later, which goes beyond the annotations. However, it does not describe the return shape or behavior when the id is not found; with no output schema, that gap remains.

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 with no filler. The core operation is front-loaded, and the second sentence earns its place by explaining why captures differ from runs and naming the linking 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 single-parameter read-only getter, the description is nearly complete: it defines the object being fetched, explains its standalone nature, and points to the follow-up action. The only minor gap is that no output format is described, but 'Get a capture' sufficiently implies the returned entity for this simple 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 description coverage is 100%: the single 'id' parameter is fully documented with a format example ('cap_abc123'). The description merely repeats the 'by id' usage without adding new parameter semantics, so the baseline of 3 applies.

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: 'Get a capture by id.' It also clarifies what a capture is ('standalone evidence') and distinguishes it from execution-bound entities like runs, helping an agent pick this over capture_list or run_get even among many 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 description gives clear usage context: captures are standalone evidence that do not need an execution upfront, so this tool is for retrieving such a capture by id. It also names the related workflow step, invariance_capture_link, for later linking to a run. It stops short of explicitly contrasting this with capture_list or other retrieval tools, so it misses full exclusionary 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?

Given annotations already indicate a non-read-only, non-destructive mutation, the description adds useful behavior: it explains the two modes (setting run_id vs. creating a link), the default target_type, and the standalone nature of captures. It does not contradict annotations and provides context beyond the structured fields, such as the legacy equivalence to invariance_capture_update.

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 two sentences, front-loaded with the core purpose. Each clause adds value: the target types, the two modes, the default, and the context about standalone evidence. There is zero fluff or redundancy, making it efficient for an agent to parse.

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 5 parameters, an output schema is absent, and the schema descriptions cover each field. The description covers the essential decision branches (run_id vs target_id), defaults, and a clarifying note about captures not needing prior execution. It does not explicitly state behavior if both run_id and target_id are provided, nor the return format, but given the openWorldHint and the succinctness, these are minor gaps. The information provided is sufficient for correct invocation in the typical cases.

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 covers all 5 parameters (100% coverage), so baseline is 3. The description adds semantic meaning beyond individual parameter descriptions by explaining the interplay: run_id is a legacy shorthand equivalent to the update tool, while target_id creates a richer link and target_type defaults to 'run'. It also notes link_type defaults server-side. This helps an agent understand how to combine parameters rather than just their isolated meanings.

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 ('link'), a resource ('capture'), and the domain (evidence-graph target) with explicit target kinds (run/case/workflow_event/node). It distinguishes itself from the sibling invariance_capture_update by noting the legacy equivalence when only run_id is used, and from unlink/links by describing the linking action. This 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?

Provides clear usage guidance by delineating two parameter-driven modes: 'with only run_id' (legacy PATCH) versus 'with target_id' (richer link), and notes the server-side default for target_type. It also adds context that captures are standalone evidence, aiding the agent's decision of when to use this tool. It does not explicitly exclude alternatives like unlink, but the distinction from the update sibling is clear enough for most use 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 indicate read-only and open-world behavior. The description adds meaningful context beyond annotations by specifying the return shape ('{ links }'), the exhaustive scope ('every evidence link'), and the conceptual distinction that captures are standalone evidence.

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 no filler: the action and return shape are front-loaded, and the sibling tool for linking is stated in the same breath.

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 simple read-only list operation with one well-documented parameter, the description covers the resource, scope, target types, return shape, and relationship to the linking operation. Nothing essential 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 100% and the sole parameter 'id' is already documented with type and example. The description adds no additional parameter semantics beyond what the schema provides, 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 and resource ('List every evidence link on a capture'), enumerates the capture target types, and names the sibling link-creation tool. The description clearly differentiates listing links from creating them.

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 clear context for when to use the tool: when listing all evidence links on a capture. It explicitly routes to invariance_capture_link for creating a link, though it does not discuss when to prefer capture_get or capture_unlink.

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 and openWorldHint=true, covering the safety profile. The description adds the 'paginated' behavior, which is also implied by the cursor and limit parameters in the schema. It does not contradict annotations and adds minimal extra behavioral context beyond what structured fields provide. Given the annotation coverage, 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?

The description is extremely concise, consisting of two sentences with no filler. The primary action and key distinguishing feature are front-loaded, and the list of filters is presented efficiently. Every word 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 list tool with readOnlyHint and no output schema, the description covers the essential elements: what it lists, that it is paginated, and the available filters. It does not detail the response format or default ordering, but these are not critical for a list operation. The description is sufficient for an agent to invoke the tool correctly, though slightly more detail on pagination usage could push it to a 5.

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% (only tags and cursor have descriptions). The description lists the filter fields but provides no semantic detail beyond their names. It does not explain how project_id, operator_id, etc., should be formatted or interpreted, nor does it compensate for the low coverage. The tool description fails to add value over the schema for most parameters, so a score of 2 is justified.

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 verb 'List' and the resource 'captures', and adds a distinguishing detail that captures are standalone evidence not requiring an execution upfront. This sets it apart from sibling tools like invariance_capture_get (single fetch), invariance_capture_create (creation), and invariance_run_list (lists runs). 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 provides clear context for when to use the tool: to list captures, and clarifies the domain-specific nature of captures (standalone evidence). It implies that for captures tied to executions, a different tool would be used, but it doesn't explicitly name alternatives or provide exclusions. This is clear context without explicit routing, which matches a score of 4.

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 discloses the behavioral effect: deleting a specific evidence link or clearing run_id. It also adds domain context ('Captures are standalone evidence; they don't need an execution upfront'), which helps explain the legacy behavior. Annotations already indicate mutation, and the description aligns with them without 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?

Three sentences, front-loaded with the main action, and zero filler. The mode distinction is stated before the supporting domain context, making the important operational detail immediately visible.

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 two-parameter tool with no output schema, the description fully covers both invocation modes, the meaning of link_id, and the legacy fallback. The domain note about captures being standalone evidence adds enough context for correct use without requiring extra documentation.

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 schema already documents both id and link_id, including the omit-to-clear-run_id behavior. The description restates this information rather than adding substantial new meaning, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Detach') and resource ('capture link'), and immediately clarifies the two operating modes (with link_id vs legacy run_id clearing). This distinguishes it from sibling tools like invariance_capture_link and invariance_capture_update without needing to inspect 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?

The description gives clear context for when to use each mode: pass link_id to detach a specific evidence link, omit it to clear the capture's run_id in the legacy path. It does not explicitly name alternatives or exclusions, but the mode distinction is actionable enough for an agent to select the right behavior.

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 mark this as a write operation (readOnlyHint=false, destructiveHint=false). The description adds context that captures are standalone evidence and don't require an execution upfront, which is useful. However, it doesn't disclose side effects beyond what's stated, such as whether metadata merging is destructive or if tags are replaced (though that's in the schema). No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences. The first sentence front-loads the core operations, and the second clarifies the capture's standalone nature and points to the link tool. No wasted words; 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?

Given there is no output schema and the input schema fully documents parameters, the description is adequate for an agent to correctly invoke the tool. It explains the standalone nature of captures and how linking works, which is important context. It doesn't cover error cases or prerequisites, but those are not essential for a straightforward mutation tool with a single required parameter.

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%, so all five parameters are already documented. The description's mention of 'merge metadata' aligns with the schema's 'shallow-merged', and 'reassign run_id' matches the schema, but it adds little beyond what the schema provides. It doesn't mention tags at all, but since schema covers them, the baseline of 3 applies.

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 the specific verb 'Update' with the resource 'capture' and enumerates the exact operations (change status, reassign run_id, merge metadata). It clearly distinguishes from invariance_capture_link by noting linking is done separately, so an agent can tell this tool apart from its 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?

It explicitly states when to use the link tool instead ('link a capture to a run later with invariance_capture_link'), providing a clear alternative. While it doesn't list every when-not scenario, the main disambiguation is covered, and the intended use (modifying an existing capture) is implicit but obvious.

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 convey that this is neither read-only nor destructive. The description adds that it closes a case by setting status to 'closed' and applying outcome fields, which is useful but does not cover reversibility, side effects, or permissions. It provides moderate additional context without contradicting 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?

A single, tightly written sentence that front-loads the action and uses the equivalence statement to convey meaningful detail without redundancy. Every part 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?

This is a simple tool with annotations covering its safety profile and a schema covering most parameters. The description plus schema are sufficient for calling the tool in typical cases, though it does not explain return behavior or edge conditions. Given the tool's simplicitychers, this is nearly 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 schema already describes outcome, closed_at, and value_usd, covering 75% of parameters; id is self-explanatory. The description mostly restates outcome and value_usd via the equivalence to invariance_case_update and does not add new parameter-level semantics. Baseline 3 is appropriate given the high schema 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 clearly identifies the action (close), the resource (case), and the intended purpose (recording an outcome). It also distinguishes itself from invariance_case_update by explicitly framing itself as a specialized equivalent, so an agent can tell them apart.

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 calls this 'the common path' and explicitly names invariance_case_update as its equivalent, providing clear context for when this tool is appropriate. It does not spell out edge cases where update should be used instead, but the common-path framing gives practical 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 already communicate readOnlyHint=false and destructiveHint=false, so it is known this is a mutating but non-destructive operation. The description adds useful behavior beyond the annotations by stating that a new case is created, that it has many related runs across time/agents/humans, and that the function returns the case so its id can be reused with invariance_run_start. It does not go into idempotency or whether duplicate cases are possible, but core behavior is clear.

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 accomplish a lot: defining the resource, giving the conceptual lifecycle, and stating the return value and next-step workflow with invariance_run_start. No filler is present, and the key actionable information 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?

Given the 7-parameter schema with full descriptions and annotations covering mutation safety, the description is complete enough. It covers the creation outcome, the return value, and how the returned id feeds into the next natural step. A small inclusion like when to use a different case-creator would make it more complete, but the current description is sufficient 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?

The input schema already has 100% description coverage for all 7 parameters, so the baseline is 3. The description does not need to repeat parameter details, and the small hints it gives (e.g., a case is aligned with a workflow instance) reinforce the meaning of workflow_key without adding explicit parameter-level guidance 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?

The description states a specific verb and resource ('Create a workflow-instance Case') and clarifies what a case is conceptually ('owns many runs across time, agents, and humans'). It distinguishes this from other case-type tools in the sibling list by emphasizing workflow instances, and it mentions using the returned id with invariance_run_start, making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to create a case: a case is a logical grouping for runs, and the returned id should be used to link subsequent runs. It does not explicitly name alternatives or exclusions (e.g., 'use invariance_eval_case_create for eval cases'), but the 'workflow-instance' framing and run-starting linkage give a strong implicit usage boundary.

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 indicate readOnlyHint=false (write operation), destructiveHint=false (non-destructive), and openWorldHint=true (potential side effects). The description adds that this attaches a semantic event, but does not disclose any potential side effects (e.g., triggering monitors, emitting signals, or affecting case state) despite the openWorldHint. It doesn't contradict annotations but fails to elaborate on behavioral traits beyond the basic write action. It does clarify the distinction from raw trace data, which is useful.

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, focused sentence that front-loads the core action, provides illustrative examples, and includes usage guidance in the second half. No wasted words; it 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 9 parameters, no output schema, and an openWorldHint, the description could be more complete. It explains the core purpose and usage but does not mention what the tool returns, any prerequisites (e.g., the case must exist), or how the event integrates with other case/event tools. It gives enough to get started but leaves gaps for an agent to fully understand the tool's place and effects.

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 78%, so most parameters are documented in the schema. The description does not add meaning for any parameters beyond what the schema provides; it only gives examples for 'type'. It does not compensate for the undocumented parameters (actor_id, actor_type) which lack schema descriptions. Since coverage is high, the baseline is 3, and the description adds marginal value here.

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 tool's action: 'Attach a semantic workflow event to a case', with concrete examples of event types. It explicitly distinguishes this from raw execution trace data ('keep raw execution trace data in runs/nodes'), which separates it from related tools like invariance_node_write or invariance_run_*. This is a specific verb+resource with a clear scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: 'Prefer this for meaningful workflow facts; keep raw execution trace data in runs/nodes.' This tells the agent when to use this tool and what to avoid. However, it doesn't explicitly mention alternatives like invariance_workflow_event_create or invariance_signal_emit, so the exclusion list is incomplete. Still, it gives a clear context for use.

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=true and openWorldHint=true, which already signal a safe, non-committal read operation. The description adds context about the semantic nature of events and their evidence-layer role, but does not disclose pagination limits, default ordering, or behavior when a case has no events. It neither contradicts annotations nor enriches them substantially.

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 efficient sentences: the first front-loads the core purpose, the second adds valuable interpretive context. No filler or redundant phrasing. The description earns its length and is easy to scan.

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 list tool with a simple schema and no output schema, the description gives enough context to understand what events are ('semantic workflow events') and their role ('queryable facts over the run/node evidence layer'). It does not mention pagination or result format, but those are partially covered by the cursor parameter description. Overall, it is functionally complete for a non-destructive operation.

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 schema describes 'id' and 'cursor' but not 'limit'. The description does not compensate by explaining the meaning of limit or how the parameters interact. With 67% schema coverage, the description adds no parameter-level value beyond what the schema already provides, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') with a clear resource ('semantic workflow events') and an explicit scope ('attached to one case'). The added phrase 'queryable facts over the run/node evidence layer' gives a nuanced definition that distinguishes it from case-level getters and workflow-level event 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?

The description implies usage contexts (e.g., when you need events for a specific case) by stating 'attached to one case', but it does not explicitly contrast it with likely alternatives such as invariance_case_evidence or invariance_workflow_event_list. No exclusions or conditions are provided, so an agent must infer when this tool is the right choice.

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, so the read-only nature is covered. The description adds the scope of returned data but does not elaborate on 'normalized' or any processing/performance implications. No contradiction, but limited added behavioral context.

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 with zero fluff. The purpose is front-loaded, and the usage guidance is a clear second sentence. Every word 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 read-only tool with a single parameter and no output schema, the description covers what it returns and when to use it. It could clarify 'normalized' further, but for its scope it is adequate.

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 only parameter 'id' is fully described in the schema with an example. The description adds no extra parameter semantics; baseline 3 applies since schema coverage is 100%.

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 ('Show') and a well-defined resource ('normalized evidence for a case') with an explicit list of components (case, runs, nodes, workflow events, actors, outcome). It differentiates from the sibling invariance_case_get by explicitly saying 'instead of only the case row.'

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 condition for use: 'when you need the full workflow execution record' and contrasts with 'only the case row,' which implies an alternative. This is explicit enough to guide the agent without naming the sibling.

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?

Beyond the readOnlyHint annotation, the description discloses that linked runs are included, ordered newest first, and capped at 100. This is useful behavioral context about response content and limits. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The first sentence front-loads the verb, resource, and key behavioral detail (runs, newest first, cap). The second sentence tells the agent what to inspect, earning 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 compensates by listing key inspectable fields (status, outcome, owner, custom_attrs) and the runs behavior. It specifies the run cap and ordering, which are essential return semantics. Minor omissions like not-found handling or run pagination are acceptable for a simple getter.

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 schema has one parameter 'id' with a complete description including an example ('case_abc123'), so schema coverage is 100%. The description does not add additional parameter-specific guidance beyond restating 'by id', which is already evident.

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 'Get' and resource 'a case by id', and distinguishes itself from siblings like invariance_case_list and invariance_run_get by noting it also returns the case's linked runs. The 'newest first, capped at 100' detail further scopes the operation.

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 'Use to inspect status, outcome, owner, custom_attrs, and the runs' gives clear context for when to use this tool. It doesn't explicitly name alternatives or exclusions, so it stops short of the highest tier, but the intended use case is well conveyed.

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 provide readOnlyHint; the description adds useful context: 'paginated' and visibility scope restricted to the calling agent. It does not contradict the annotations and makes no misleading claims about side effects.

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: the first front-loads the main action and pagination, the second lists available filters. No redundant wording or 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 read-only, paginated list tool, the description plus schema adequately covers filter semantics and cursor handling. The lack of an output schema leaves return shape unstated, but this is a minor gap given the simple list operation and existing annotations.

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 25%, so the description compensates by enumerating six filter parameters and the status enum. However, it does not explain limit/cursor beyond what the schema already says and gives no additional format detail for outcome or tags.

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'), a clear resource ('cases'), and a scope ('visible to the calling agent'), plus pagination. This clearly differentiates it from siblings like invariance_case_get (single case) and invariance_case_create (write operation).

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 what the tool does but gives no guidance on when to choose it over related tools such as invariance_case_get or invariance_finding_list. No alternatives or exclusions are mentioned, so an agent must infer usage context from the name alone.

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 indicate a write operation (readOnlyHint false) and openWorldHint true. The description adds a shallow-merge detail for custom_attrs and mentions status transitions, but doesn't disclose side effects like required presence of outcome for status close or behavior of other fields. It doesn't contradict annotations, but adds limited behavioral context beyond the 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?

The description is two concise sentences with no fluff. It front-loads the primary actions and ends with an alternative routing, making it easy for an agent to digest quickly.

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?

This is a mutation tool with 8 parameters, 50% schema coverage, openWorldHint true, and no output schema. The description does not mention required conditions (e.g., outcome needed for status='closed'), return format, or other side effects. Given the complexity and the open-world nature, more context is needed for safe 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?

With schema description coverage at 50%, half of the parameters (id, owner, status, closed_at) lack schema descriptions. The description only names owner, custom_attrs, and status, and the custom_attrs shallow-merge info is already present in the schema. It fails to compensate for the undocumented parameters or add extra semantics for them.

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 verb 'update' with the resource 'case' and enumerates the main types of updates: owner, custom_attrs, and status. It also distinguishes this tool from the sibling invariance_case_close, making the purpose 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?

It explicitly directs the agent to use invariance_case_close for the common 'set outcome + close' path, providing a clear alternative for a specific scenario. The listing of update types also gives implicit guidance on when this tool is appropriate.

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 no annotations on the tool, the description carries the full burden of behavioral disclosure. It provides none – no mention of side effects, required permissions, rate limits, or return behavior. It is a bare alias with zero behavioral context.

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 only a single sentence, which is concise, but it is underspecified rather than appropriately minimal. It lacks any structure or essential detail, making it a placeholder rather than a useful definition.

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 the tool's complexity (at least one parameter, no output schema, no annotations), the description is entirely insufficient. An agent would need to look up invariance_run_start to understand behavior, which is not provided. This is a critical gap 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 description coverage is 0% (there is no description for the 'name' parameter) and the description adds nothing about parameters. The agent cannot infer what 'name' refers to – run name, agent name, or something else. The description offers no compensation for the schema 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?

The description is a tautology – 'Alias of invariance_run_start' restates the tool's identity without explaining what it does. It does not mention starting or creating a run, nor does it distinguish itself from the canonical invariance_run_start or any sibling. An agent gains no functional understanding.

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 invariance_run_start or other run-related tools. No exclusions, no context, no indication of prerequisites. The alias reference is an implicit pointer, but not an explicit usage guideline.

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 establish that this is a read-only operation (readOnlyHint=true) and open-world (openWorldHint=true). The description says 'get,' which is consistent with those annotations and adds no contradictory or surprising behavior. However, it also provides no additional behavioral context beyond what the annotations already 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?

The description is a single, front-loaded sentence with zero wasted words. It is appropriately concise for a simple single-resource getter and contains no filler or redundant phrasing.

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 one simple parameter and read-only annotations, the description is minimally viable: the agent knows to supply an ID. However, 'divergence' is domain-specific jargon, and there is no mention of where IDs come from or what the response contains, so an agent unfamiliar with the domain would still lack meaningful context.

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%, so the description carries the burden of explaining the 'id' parameter. 'By ID' conveys that the id is a divergence identifier, but that is only slightly more than the parameter name itself. It does not explain the ID format, how to obtain valid IDs, or the meaning of the returned divergence.

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 ('Get'), a specific resource ('divergence'), and the retrieval scope ('by ID'). This clearly differentiates it from sibling tools like invariance_divergence_list and invariance_divergence_update, so an agent can identify what this tool does without needing to open its 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?

There is no guidance about when to use this tool versus alternatives. It does not mention invariance_divergence_list for enumerating divergences or invariance_divergence_update for modifying one, nor does it describe any exclusions or preconditions. The agent must infer usage from the tool name alone.

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 and openWorldHint=true, so the safety and volatility profile is covered. The description adds a useful scoping note ('visible to the caller'), but does not disclose pagination behavior, result ordering, or any other behavioral specifics. Given annotations, the bar is lower, but the description adds only marginal value beyond them.

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 extremely concise and front-loaded: it states the action and resource, defines the term, and lists the filters in a single sentence. No words are wasted, and the most critical information appears first.

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 list tool with six optional parameters and no output schema, the description is minimal but sufficient to understand the basic operation. It lacks guidance on pagination (cursor/limit), which is indirectly described in the schema, and does not mention any default behavior. Given the complexity and lack of output schema, it could do more, but it is not dangerously incomplete.

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 17% (only cursor has a description). The description compensates by naming the filter dimensions (run, kind, severity, status), which clarifies those parameters' roles. However, it does not explain limit or cursor behavior, nor provide meaning for enum values. It partially covers the gap but not fully, so a 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('List') and the resource ('divergences'), and defines divergences as 'expected-vs-observed gaps' to disambiguate the concept. It also lists the filtering dimensions (run, kind, severity, status). However, it does not explicitly distinguish itself from sibling tools like invariance_finding_list or invariance_monitor_list, 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 description provides no guidance on when to use this tool versus other list-type tools (e.g., invariance_finding_list, invariance_monitor_list). It does not mention exclusions, prerequisites, or contexts where an alternative would be more appropriate. An agent has to infer usage from the resource name alone.

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 indicate a write operation (readOnlyHint=false) and non-destructive behavior (destructiveHint=false), so the description only needs to add nuance. The word 'transition' correctly implies a state-machine operation, but the description doesn't disclose whether transitions are validated, idempotent, or have side effects.

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 filler. Every word contributes to the core action and the accepted status values, making it appropriately concise.

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 simple two-parameter tool with an enum, the description is nearly sufficient, but it omits key operational details such as allowed transition paths and the meaning of the id parameter. Without an output schema, there is also no mention of what the tool returns, leaving some context incomplete.

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%, so the description must compensate. It lists the possible status values but provides no meaning for the 'id' parameter, no explanation of the statuses, and no guidance on which transitions are permitted. This is minimal compensation for a fully undocumented 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?

The description clearly identifies the action as a status transition on a divergence, and lists the target statuses. It distinguishes itself from sibling read tools like invariance_divergence_get/list through the explicit 'transition' verb, though it doesn't define what a divergence is or which transitions are valid.

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 context is implied rather than explicit: the verb 'transition' and the sibling list/get tools suggest it is for changing a divergence's status versus reading it. There is no direct statement of when to use this tool versus alternatives or any 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 provide the core behavioral facts (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds that the candidate becomes 'eligible for promotion,' which is a meaningful state change. However, it does not clarify reversibility, whether accepted candidates can be later rejected, or what happens to related edge 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?

The description is a single sentence with no filler. It front-loads the verb and resource, then states the outcome immediately. Every word contributes 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?

For a single-required-parameter tool with no output schema and full annotation context, the description covers the core action and result. It lacks explicit workflow context about when accepting differs from promoting, but the one-parameter complexity and the clear outcome make it mostly complete for basic usage.

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%, so the 'id' parameter is already fully documented as an edge candidate ID. The tool description adds no extra semantic detail about the parameter, so schema carries the entire parameter meaning, which is adequate for a one-parameter 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 and resource: 'Accept a proposed DNA edge candidate' and clearly states the outcome: 'making it eligible for promotion into a durable semantic link.' This distinguishes it from the sibling promote tool by describing a pre-promotion state rather than the final promotion itself.

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 is given. The description does not mention when to use accept versus reject_edge_candidate or promote_edge_candidate, nor does it explain the working relationship to those siblings. An agent cannot tell whether acceptance is a required predecessor to promotion or an alternative step.

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 and openWorldHint, so the safety profile is covered. The description adds useful behavioral details beyond annotations: output shape ({data: DnaEdgeCandidate[], next_cursor}), the 'awaiting review' semantic, and the available status filter values. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences with no filler. The verb and resource are front-loaded, the key filters are summarized, and the output shape is compressed into a single line. 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 read-only list tool with no required parameters, the description is nearly complete: it conveys purpose, optional filters, and return shape, and pagination is signaled via next_cursor. The main gaps are the undocumented project_id filter and lack of detail on relation_kind values, but these are optional filtering concerns rather than blockers to invoking the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low (33%), so the description must compensate. It does clarify that status, object_id, and relation_kind are filters and enumerates the status values, which adds value. However, project_id is left undocumented in both the schema and description, and relation_kind's meaning is not expanded, so the compensation is partial.

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 ('List'), a specific resource ('Company DNA edge candidates'), and the defining context ('discovered relationships between objects awaiting review'). It also lists the available filters, making it easy to distinguish from siblings like invariance_dna_list_edges and invariance_dna_list_objects.

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 'awaiting review' framing clearly situates this tool in the candidate-review workflow, alongside siblings like invariance_dna_accept_edge_candidate and invariance_dna_reject_edge_candidate. It does not explicitly say when to prefer invariance_dna_list_edges over this tool, but the context is clear enough for an agent to choose appropriately.

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 and openWorldHint=true, covering safety. The description adds useful behavioral context beyond annotations: the exact output shape ({data: DnaEdge[], next_cursor}) and pagination token semantics, which are not inferable from the schema or annotations. It does not contradict annotations and provides non-obvious details about the return format.

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 two sentences, front-loads the core purpose, includes a clarifying example, and ends with a compact output format. Every clause earns its place; there is no redundant or padding text. This is precisely engineered for an agent scanning multiple tool definitions.

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 list tool with no output schema, the description covers the essential behavior: what it lists, example, filters, and response shape. It does not state default ordering, behavior when no filters are provided, or the relationship to the similar invariance_run_operational_graph tool. Those are minor gaps given the schema and annotations, but a note about empty-filter behavior would make it fully 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 80% because four of five parameters (kind, cursor, run_id, entity_id) have descriptions; limit lacks one. The description repeats that run_id, kind, and entity_id are filters, but adds no new semantic detail beyond the schema. Since the schema already documents these parameters well, 3 is the appropriate 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 states a specific verb and resource ('List durable Company DNA edges') and gives a concrete example ('refund -[REQUIRED]-> policy'). It distinguishes itself from sibling tools like invariance_dna_list_edge_candidates by using 'durable' and from object-listing tools by focusing on relationships/edges. This leaves no ambiguity about what the tool returns.

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 use for listing confirmed/durable edges and mentions filter dimensions (run_id, kind, entity_id). However, it does not explicitly state when to use this versus alternatives like invariance_run_operational_graph or invariance_dna_list_edge_candidates, nor does it mention any exclusions. Usage context is present but implicit, not actionable for an agent deciding among many sibling 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 already mark this as read-only and open-world, so the description does not need to restate safety. It adds useful behavior beyond the schema by explaining that mentions are extracted from events/chunks, may only resolve to objects, and that the response is a paginated {data, next_cursor} structure.

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 compact and front-loaded: one sentence defines the tool, the next covers filtering and output. There is no filler, and the pagination contract is included without extra ceremony.

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 list operation with no output schema, the description adequately supplies the return shape, pagination mechanism, and main filter dimensions. It does not document project_id or mention_type values, but since all parameters are optional and read-only behavior is covered by annotations, these are moderate rather than critical omissions.

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 57%, with event_id, chunk_id, object_id, and cursor already described. The description mostly restates those filter names and adds only a light semantic nuance about object resolution. It does not explain limit behavior, project_id scoping, or acceptable mention_type values, leaving meaningful gaps.

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 opens with a specific verb and resource: 'List Company DNA object mentions.' It defines those mentions as extracted references that may resolve to a DNA object, which clearly separates this tool from sibling tools like invariance_dna_list_objects.

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 useful invocation context by listing the available filter dimensions and the paginated output shape. However, it never explicitly states when to prefer this tool over invariance_dna_list_objects or the DNA edge-candidate tools, so the routing guidance is implied rather than 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 carry readOnlyHint=true and openWorldHint=true, so the bar for the description is lower. The output format '{data: DnaObject[], next_cursor}' adds useful behavioral context about the return shape and pagination. It does not add detail on auth, rate limits, or edge cases, but it's not required here given 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?

The description is three sentences: purpose, filtering, output. Everything a caller needs is present, and no word is wasted. It front-loads the action ('List') and the core meaning ('Company DNA objects'). Ideal conciseness.

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 list tool, the output shape and basic filter modes are covered. However, without an output schema, the description should probably address the meaning of the DnaObject type, which it only hints at with the examples, and the project_id field's role is left completely unexplained. The tool is otherwise minimally complex, so a 3 feels fair.

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 60% — the descriptions for q, kind, and cursor already exist, while limit is only schema-bounded and project_id has no field description. The tool description only restates 'Filter by kind or a free-text query q'; it does not explain kinky semantics, project_id's role, or how limit/cursor interplay with the output. It adds little value beyond the schema for the mostly already-described parameters.

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 and resource — 'List' + 'Company DNA objects' — and clarifies what those are: 'the canonical operational entities in a project's DNA graph (e.g. tickets, services, policies)'. This clearly states the function and implicitly separates it from sibling tools like invariance_dna_list_edges or invariance_dna_list_object_mentions, though it never names them. It's clear but not explicitly differentiated from 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 description gives no guidance about when to choose this tool over alternatives like invariance_dna_list_object_mentions, invariance_dna_list_edges, or invariance_node_list. There is no mention of when not to use it or what the other tools are for. The only implicit signal is the focus on 'canonical' objects, which is not enough to route the agent correctly.

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 substantial behavioral detail beyond the minimal annotations: idempotency with already_promoted=true, a 422 failure mode, and dry_run semantics that preview without writing. This clearly communicates that the operation writes durable state while being safe to retry.

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 convey the core action, prerequisites, failure condition, idempotency, and dry_run option with no filler. The main verb and object are front-loaded, and 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 two-parameter mutation tool with no output schema, the description covers prerequisites, failure modes, idempotent behavior, and dry_run. It tells the agent what to expect on re-promotion and preview, though the normal success response format is not fully described.

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 100%, so the schema already documents both id and dry_run. The description reinforces dry_run behavior ('preview the would-be link without writing') but does not add significant new parameter-level meaning beyond what the schema provides.

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 a specific action ('Promote an accepted DNA edge candidate into a durable semantic link') with a specific resource. It distinguishes itself from related DNA candidate tools by focusing on the promote step rather than accept/reject/list.

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 explicit preconditions for when the tool can be used: candidate must be accepted, carry a semantic_similarity signal, and have at least two evidence chunks. It implies a workflow order (accept before promote) and mentions dry_run for preview, though it does not explicitly name alternative tools for rejection or listing.

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 indicate readOnlyHint=false and destructiveHint=false, so the description's claim that rejection means 'never promoted' adds meaningful behavioral context. However, it doesn't disclose whether rejection is reversible, whether it affects related candidates, or what the response looks like. The description adds some value beyond annotations but not rich detail.

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?

One sentence, zero waste, and the key outcome ('never promoted') is front-loaded. Every word 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 single-parameter tool with no output schema, the description is adequate: it states the action and the consequence. However, it doesn't clarify whether rejection is permanent or reversible, which could matter for an agent deciding between reject and other candidate-management tools. Given the tool's simplicity, this is a minor 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 100% and the single parameter 'id' is described as 'Edge candidate ID.' The description adds no additional meaning beyond the schema, 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?

The description states a specific verb ('Reject') and resource ('DNA edge candidate') with a clear outcome ('so it is never promoted'). It distinguishes from siblings like accept_edge_candidate and promote_edge_candidate, though it doesn't explicitly name them.

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 when to use it: when an edge candidate should be rejected and never promoted. However, it doesn't explicitly state when not to use it or mention alternatives like accept_edge_candidate or promote_edge_candidate, leaving some inference to the agent.

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 establish readOnlyHint=true, and the description adds specific behavioral context: it checks API key auth, API reachability, and reports name/version, and it mirrors the CLI's JSON output. This gives the agent a clear model of what the call inspects without overpromising side effects.

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-load the core purpose, then specify the CLI mirror and return shape. Every clause adds information, with no repetition or 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 simple, zero-parameter, read-only diagnostic tool, the description is complete: it states the checks performed, notes the CLI equivalence, and documents the return shape. No output schema exists, so including the return structure is especially valuable and 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?

With zero parameters and an empty input schema, there is no parameter information to document. The baseline for a no-parameter tool is 4, and the description sufficiently explains what the invocation does.

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 and resource ('Run a health check on this MCP server') and enumerates exactly what it verifies: API key auth, API reachability, and server name/version. This clearly distinguishes it from the large set of sibling tools, none of which offer a server-wide diagnostic.

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 intended use case is implied by the description: call this when you need to verify server auth, connectivity, or identity. However, it does not explicitly state when to use it versus alternatives, provide exclusions, or name a fallback tool. The guidance is adequate but 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 disclose readOnlyHint=false and destructiveHint=false, so the description aligns with those but does not add any further behavioral context beyond stating the add operation. Given the openWorldHint=true, the description would benefit from noting idempotency, preconditions, or potential side effects, but none are provided.

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 concise single sentence with no redundant words. It front-loads the verb and core resource, making it easy to process. It earns a 4 because while it is efficient, it could include a bit more context (such as clarifying the required suite_id) without much cost, but as-is it is well-structured.

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 simple creation tool with few parameters and no output schema, the description is moderately complete. It covers the main action but omits important context like whether the eval suite must exist, how to obtain a suite_id, or how this tool compares to case-creation-from-run. These gaps prevent full completeness.

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 partially explains the body parameter as 'a case (input + expected)', which adds meaning to the JSON object schema. It does not add specific meaning to suite_id, though 'to an eval suite' implies the suite_id parameter is the target. With schema coverage at 50%, this adds some semantic value but does not fully compensate for the undocumented suite_id.

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 verb and resource: 'Add a case (input + expected) to an eval suite.' It is specific about the action and target resource, distinguishing this from generic case tools to some degree. However, it does not explicitly differentiate from related siblings like invariance_eval_case_create_from_run or invariance_case_create, so it misses the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention cases where the user should use invariance_eval_case_create_from_run, invariance_case_create, or other case-related tools. The purpose is implicit but there are no use-mode exclusions or alternative 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 communicate that this is a non-read-only, non-destructive operation, and the description adds that it copies the run's input/output as expected. It does not explain side effects such as how provenance is stored or whether the source run is left untouched, but the annotation coverage lowers the burden.

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 one well-structured, front-loaded sentence with no fluff. It states the action, source, destination, and captured content efficiently without repeating schema details.

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 two-parameter creation tool with no output schema, this is minimally adequate, but it does not describe the return value or what the agent should expect after invocation. An agent would need to infer response behavior from convention rather than from this definition.

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 schema documents `body` thoroughly, including required source_run_id, optional fields, and an example, but `suite_id` has no description. With 50% schema coverage, the tool description should compensate for that gap; it only partially does via the phrase 'in a suite'.

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 ('Snapshot ... as a new eval case') and identifies both the source resource (existing production run) and the target (eval case in a suite). It also states what is captured, 'input + output as expected', which clearly distinguishes it from generic case-creation tools like invariance_eval_case_create.

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 'Snapshot an existing production run' gives clear context for when this tool is appropriate, and 'in a suite' clarifies the destination. It does not explicitly name alternatives or exclusion conditions, but the usage scenario is direct enough that an agent can choose it over generic eval case creation.

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 signal a safe read-only operation (readOnlyHint=true). The description adds only 'paginated', which is partly redundant with the cursor/limit parameters, but it does not misrepresent behavior and no contradiction exists.

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 zero filler. Every word contributes to identifying the resource and operation.

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 simple paginated list operation, the description plus schema is nearly sufficient: suite_id is required, pagination is signaled, and cursor semantics are documented in the schema. A richer definition could clarify ordering or default limit, but these are minor for an agent 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 33% (cursor only), so the description carries some weight. It clarifies that suite_id selects an eval suite and that limit/cursor relate to pagination, but it gives no detail on defaults or response shape 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?

The description states a specific action and resource: 'List cases for an eval suite'. The phrase 'for an eval suite' adds scope that distinguishes it from generic case listing tools, though it does not name a sibling such as invariance_case_list.

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 guidance is provided about when to use this tool instead of alternatives like invariance_case_list or invariance_eval_case_get. The only usage cue is implied by the resource scope; there is no when-not-to-use or explicit alternative.

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 convey that this is a non-read-only but non-destructive operation. The description adds minimal behavioral context beyond the act of appending; it does not explain validation behavior, idempotency, ordering, or failure modes. It does not contradict the annotations, but adds little beyond them.

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 sentence that front-loads the action, resource, and scope with no filler. Every word earns its place and the sentence is immediately digestible.

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 two-parameter append operation, the combination of the concise description and the detailed schema provides enough information to invoke the tool correctly. The lack of output schema is acceptable since return values are not essential for an append operation, though error conditions are not described.

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 body parameter is well-documented with required/optional fields and a concrete example. The description's mention of 'input + expected output' mirrors schema content, so it adds no significant meaning beyond what the schema already provides.

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 ('Append') with a clear resource ('a single example row ... to an existing dataset') and specifies the row's composition ('input + expected output'). This clearly distinguishes it from dataset creation, listing, and seed-suite tools among the 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 'existing dataset' and 'single example row' imply this is for incremental additions rather than dataset creation or bulk seeding, but no explicit when-to-use guidance or alternatives are named. The usage context is inferable but not directly 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 communicate readOnlyHint=false, destructiveHint=false, and openWorldHint=true, and the description does not contradict them. The description adds that the dataset is reusable and holds example rows, but it does not disclose duplicate-name behavior, return value, persistence semantics, or permissions requirements. Given annotations cover safety basics, this is slightly above neutral but still leaves behavioral gaps.

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 sentence that front-loads the action and definition. There is no redundancy or filler; every part adds clarity about what the dataset is and why it is used.

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 one-parameter tool with full schema coverage and no output schema, the description adequately explains the core concept and use case. It leaves minor details unstated (e.g., what object is returned, whether names must be unique), but an agent has enough to correctly invoke it.

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 only parameter, body, is already documented with a schema description, required/optional fields, and an example, giving it 100% schema coverage. The tool-level description adds that the dataset drives experiments—useful context—but the parameter's exact JSON format is already fully handled by 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?

The description names the specific action and resource ('Create a reusable eval dataset') and defines the resource as a 'named collection of input/expected example rows used to drive experiments'. This clearly identifies what tool does and distinguishes it from siblings like list/get/append example tools, though it does not explicitly name 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 description provides no guidance on when to choose this tool over alternatives. It does not mention that this is the first step before appending examples, nor how it relates to eval_suite_create or eval_case_create. There are no prerequisites, exclusions, or alternative routing conditions stated beyond the implied 'use this to create a 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds the pagination behavior, which is useful but already reflected in the tool name and cursor parameter. It does not explain what a response contains or whether results are bounded.

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 entire description is one compact, front-loaded sentence with no filler. It conveys the core action, the resource, and the pagination trait efficiently.

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 simple paginated list operation, the description is mostly adequate, but it omits the meaning of the required 'id' parameter and any indication of the response shape. With no output schema, some additional detail about the returned rows would improve completeness, though the core call 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 description coverage is only 33%, so the description must compensate for undocumented parameters. It does not explain that 'id' refers to the target dataset or clarify how 'limit' controls page size, leaving the agent to infer these meanings from the tool name 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 uses a specific verb ('List'), a clear resource ('example rows for a dataset'), and notes pagination. This distinguishes it from sibling tools like invariance_eval_dataset_list and invariance_eval_dataset_get, which operate on datasets themselves rather than their example rows.

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 guidance is given on when to use this tool versus alternatives, such as invariance_eval_dataset_get or invariance_eval_dataset_append_example. The description does not mention any preconditions, output size limits, or cases where another tool would be more appropriate.

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 and openWorldHint=true, covering the safety and openness profile. The description adds no further behavioral details such as error handling, return format, or side effects. Since the bar is lowered by annotations, a 3 is appropriate—it provides no additional context beyond what the annotations already 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?

The description is one short sentence, front-loaded with the core action and object, with zero redundant words. It precisely captures the tool's purpose without elaboration, embodying conciseness.

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 simple get-by-ID tool with one parameter, the description and schema cover the invocation. The absence of an output schema is mitigated by the clear implication that the tool returns the requested eval dataset, as indicated by the name and description. No additional conditions or prerequisites are missing. A 4 is justified—it's complete for its simplicity, though a mention of the return payload would make it a 5.

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 'id' parameter is fully described in the schema with an example. The description's phrase 'by ID' adds no extra meaning beyond the schema. With high coverage, the baseline of 3 applies, and the description doesn't compensate for anything missing.

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 'Get a single eval dataset by ID' uses a specific verb (Get), identifies the resource (eval dataset), and specifies the key (by ID). This clearly differentiates it from sibling tools like invariance_eval_dataset_list (which likely retrieves multiple) and invariance_eval_dataset_append_example. An agent can immediately understand the tool's singular purpose.

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 clearly implies usage when the agent has a specific dataset ID, and the parameter schema requires it. It doesn't explicitly name alternatives or state when not to use it, but the 'by ID' phrasing provides strong contextual signal. No exclusions are mentioned, but given the simplicity of a get-by-id operation, the context is clear enough for an agent to select it appropriately.

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 and openWorldHint=true, so no contradiction is present. The description adds useful behavioral context beyond those annotations: results are scoped to the calling agent's visibility and returned in paginated form, which helps the agent understand what to expect.

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 that communicates the core action, scope, and pagination behavior with no filler. Every word 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 low-complexity read-only list operation with no output schema, the description covers purpose, visibility scope, and pagination. The schema handles the remaining parameter details, so nothing critical is missing 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 description coverage is 50%, with cursor fully documented but limit lacking a description. The description's mention of pagination helps the agent infer limit as a page size and cursor as a continuation token, but it does not fully compensate for the missing limit 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?

The description states a specific verb and resource: 'List eval datasets visible to the calling agent (paginated).' It clearly distinguishes this from related sibling tools like invariance_eval_dataset_get, invariance_eval_suite_list, and invariance_eval_dataset_examples_list.

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 makes the tool's scope clear with 'visible to the calling agent' and 'paginated,' which contextualizes when to use it. It does not explicitly name alternatives or exclusion criteria, but the list-oriented phrasing and pagination signal are sufficient guidance for this simple read tool.

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 indicate readOnlyHint=false (mutation), destructiveHint=false, and openWorldHint=true. The description adds that it can create a dataset, append rows, create a suite, create cases, and optionally start an eval run (side effects). It doesn't mention any destructive actions or irreversible changes, which aligns with the annotations. It could add more detail about whether the run is started synchronously or async, but the basics are covered.

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 very short (two sentences) and front-loaded with the key action ('One-call eval setup'). Every sentence adds value: the first states the scope and steps, the second positions it as the preferred MCP path. 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 tool with a single parameter that has 100% schema coverage and a rich example embedded in the schema, the description is sufficient for an agent to understand the tool's purpose and main flow. It could mention what happens if run=true (side effects), but the schema's example covers the format. The output is not defined, but the tool produces side effects rather than returns, which is acceptable. Overall, it's nearly 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 schema description coverage is 100% and the schema already describes the body parameter in detail, including required and optional fields with an example. The description adds minimal extra meaning beyond what the schema provides, just emphasizing the one-call orchestration. Thus, 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?

The description clearly states a specific verb ('One-call eval setup') and resource ('dataset, suite, cases, run'), and distinguishes it as the preferred MCP path for turning JSON examples into runnable evals, which differentiates it from the many sibling tools like invariance_eval_dataset_create and invariance_eval_suite_create.

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 frames itself as the 'preferred MCP path' for converting JSON examples into runnable evals, giving clear context. It also implies when to use it over manual multi-step tools (create dataset, append rows, etc.), though it doesn't name alternatives explicitly. Still, the guidance is strong and actionable for an agent.

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 and openWorldHint=true, so the description doesn't need to restate safety. It adds value by disclosing the output format (CompareResponse with per-case ScoreDelta entries and aggregate deltas), which goes beyond the annotations. No contradictions found.

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 that states the action, output, and purpose with zero waste. It is concise and immediately informative.

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 the read-only nature (annotations) and fully documented parameters (schema), the description provides sufficient context for an agent to call it correctly. It mentions the output structure, though it doesn't cover edge cases like missing runs or error handling, which are not critical for a read-only comparison 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 description coverage is 100% and both parameters are well-documented: 'id' is the new/candidate run, 'baseline' is the baseline to diff against. The description adds no further parameter detail beyond what the schema already provides, so it stays at the baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'compare', the resource 'two scored eval runs', and specifies the output structure (CompareResponse with per-case ScoreDelta and aggregate deltas). It distinguishes this from sibling tools like invariance_run_metrics or invariance_eval_run_results by focusing on case-by-case comparison against a baseline.

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 an explicit use case: 'Use to surface regressions vs. a baseline.' This tells the agent when to invoke it. It doesn't explicitly contrast with alternatives, but the context of comparing runs vs. getting metrics is clear enough given the sibling names.

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 signal readOnlyHint=false and openWorldHint=true, so the description adds context beyond that: it states it 'Populates eval_results.scores' and 'records a baseline run'—concrete behavioral effects. It does not contradict the annotations and provides useful information about side effects and the baseline storage.

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 succinct and front-loaded: a single main sentence stating the purpose, immediately followed by the key details—the effect on eval_results.scores and a list of built-in scorers. No filler, every word contributes to understanding what the tool does and how to invoke 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 tool with no output schema, the description covers the essential inputs (id, body with required scorer_specs and optional baseline_run_id), the format of the body, and the built-in scorers with config hints. It could mention potential prerequisites (e.g., does the run need to be finished?) but the openWorldHint annotation somewhat accounts for unexpected side effects. Overall, it is sufficiently complete for an agent to make a correct call.

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 100%, with both parameters documented. The description adds significant extra meaning: it lists the built-in scorer names, explains the config.tolerance format for numeric_tolerance, and gives a concrete example of the body structure including baseline_run_id. This goes beyond the minimal schema description and helps the agent construct a valid request.

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: 'Execute an experiment against an existing eval run' and clarifies exactly what it does—applies scorer specs to every case result and optionally records a baseline run. It names the built-in scorers and the effect on eval_results.scores, which clearly distinguishes it from siblings like invariance_eval_suite_run or invariance_eval_experiment_compare.

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 clear context: you use this when you have an existing eval run and want to score its results with a list of scorer specs, optionally recording a baseline. It does not explicitly mention alternatives or when not to use it, but the purpose is unambiguous enough for an agent to pick it appropriately among the many sibling 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 already establish readOnlyHint=trueable true and openWorldHint=true, so the safety profile is covered. The description adds useful context by listing the returned data categories, but does not mention behavior like error cases, response shape beyond the field names, or any limits. The added value is real but modest.

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?

One short sentence with the core action front-loaded and a parenthetical summarizing the return contents. There is no fluff or repetition; every part contributes useful 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 single-parameter read-only getter, the description covers the key facts: what it returns and the input. There is no output schema, so listing the return contents is necessary and done. It could have added marginal details like pagination or error behavior, but the simplicity of the tool makes the description 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 100% and the single id parameter is already clearly documented with an example. The tool description does not add any additional meaning for the parameter beyond restating that it identifies the eval run. Baseline of 3 is appropriate when the schema handles parameter 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?

The description uses a specific verb ('Get') and resource ('eval run') and names the key data fields returned (status, aggregate counts, timestamps, scorer specs). It clearly identifies the tool's function, but does not explicitly distinguish it from similar sibling getters like invariance_run_get or invariance_eval_run_results.

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 guidance is provided about when to use this tool versus alternatives such as invariance_run_get, invariance_run_inspect, or invariance_eval_run_results. The context signals show a dense cluster of run-related tools, so the description leaves the agent without any routing information.

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 mark readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context about the result structure (scores per-scorer in 0..1, pass/fail) and pagination, but does not go beyond that. It does not contradict 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 purpose, then the result structure. Every word earns its place; no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only paginated listing tool with no output schema, the description covers the returned fields and pagination. It doesn't mention error handling or edge cases, but annotations (readOnly, openWorld) and the schema's cursor documentation fill most gaps. It is sufficiently complete for an agent to call 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 coverage is low (33%); only 'cursor' has a schema description. The description adds the pagination context and the meaning of 'id' (eval run) implicitly, and the 'limit' is left to the schema's max 200. It partially compensates for the gap but doesn't explicitly define each parameter's role beyond what the name implies.

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 ('List') and resource ('per-case results for an eval run'), and explicitly enumerates the fields returned (output, expected, scores 0..1, pass/fail). This distinguishes it from sibling tools like invariance_eval_run_get (which likely returns run-level metadata) and invariance_eval_case_list (which lists cases of a dataset).

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 makes clear this tool lists detailed per-case results for a given eval run, and mentions pagination. However, it does not explicitly mention when to prefer this over alternatives (e.g., run summary via invariance_eval_run_get) or when not to use it. The context is clear but without exclusion 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 indicate readOnlyHint=false and destructiveHint=false, meaning this is a creation operation with no destructive side effects, and the description aligns by stating 'Register'. It adds some context about the scoring rule's behavior (0..1 score) but does not disclose potential errors (e.g., duplicate names), validation requirements, or response format. Given the minimal annotations, the description could provide more behavioral detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the verb and resource, includes a parenthetical definition, and lists the built-in kinds without redundancy. It is concise and every part contributes to understanding the tool's purpose and usage.

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 the tool has only one parameter but that parameter is a complex JSON string, the description covers the essential aspects: the purpose, required fields, optional config, and built-in kinds. However, it does not specify what the response contains (e.g., the created scorer object or ID) since there is no output schema, nor does it address uniqueness constraints or error scenarios, which would improve completeness for a creation 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?

The schema already describes the 'body' parameter as a JSON string with required fields name and kind, and optional config, achieving 100% coverage. The tool description adds value by enumerating the built-in kinds (exact_match, contains, etc.) and providing an example config, which enriches the schema's otherwise generic description and helps the agent construct valid requests.

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 tool registers a scorer and defines what a scorer is (a named scoring rule mapping output+expected to a 0..1 score). It also lists built-in scorer kinds, distinguishing it from sibling list tools like invariance_eval_scorer_list and invariance_eval_scorers_list_builtin, which only retrieve existing scorers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.