Enoki

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

Beyond the annotations, the description discloses that the run stops in about five seconds, keeps already-produced findings and probes, returns immediately, requires the test:run scope, and treats cancellation of an already-finished run as a conflict. It also gives an important interpretive warning about cancelled-run verdicts and categories_completed. This is substantively richer than the destructiveHint/idempotentHint annotations 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?

The purpose and the key counterpart relationship are front-loaded, and the later sentences carry useful operational and interpretive warnings rather than filler. It is somewhat long for a one-parameter tool, but every section adds concrete 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?

With an output schema present, the description does not need to explain return values, and it still covers timing, polling behavior, conflict handling, required scope, and the important caveat about partial results. An agent has enough context to invoke and interpret the tool 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 0% and the sole required parameter, run_id, has no description in the schema. The tool description does not explain what run_id is, where to obtain it, or its expected format, so it fails to compensate 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 uses a specific verb and resource ('Ask a running assessment to stop') and explicitly distinguishes the tool from its sibling trigger_assessment as its counterpart. It also clarifies the intended scope: a run you started against the wrong target or no longer need.

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

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

It states exactly when to use the tool ('for a run you started against the wrong target or no longer need') and when not to expect success ('A run that has already finished is a conflict, not a retryable error'). It also names the follow-up tool, get_assessment_status, for polling, which effectively routes the agent to the right alternative after cancellation.

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 destructiveHint=true and idempotentHint=true already declared, the description still earns credit by adding the auth requirement ('Requires the write scope') and the downstream consequence that a dismissal influences later assessments of the same agent. It does not say whether a closed finding can be reopened or what happens when closing an already-closed finding, which matters for a destructive mutation.

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, no filler, and the core action plus its precondition are front-loaded before the parameter rules. Every clause adds new 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?

An output schema exists, so return values need not be described, and the description covers the prerequisites, side effects, and the conditional parameter rule. What remains thin is the lifecycle context: reversibility of a close and how this differs from retract_non_issue.

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 and largely does: it explains the status values, the mandatory explanation with a 1-4000 character bound, and that reason_code is a category required only for dismissals. finding_id is left unexplained but is self-evident from the resource.

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 ('Close a finding') plus the two terminal states it can set ('fixed', 'dismissed'), so the operation is unambiguous. The distinction between resolved and not-a-real-issue maps directly onto the enum values in the schema.

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

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

'Close a finding once you have resolved it' gives a clear precondition, and the description tells the agent which status to choose for a non-issue. However, it never names the related siblings (validate_fix, retract_non_issue) that a confused agent might reach for instead, so the alternative-selection guidance is incomplete.

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?

Adds real value beyond the annotations: it discloses the write-scope requirement, the return shape (profile id and new version), and the downstream effect that confirmed values can make an assessment rule a finding out. However, annotations declare destructiveHint=true while the description insists it makes values 'the customer's without changing them' and never explains what is lost or overwritten (e.g., prior auto-discovered values).

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?

It is compact and front-loads the purpose, but the middle sentence is a run-on that crams both `answers` and `items` into opaque jargon ('the text between its fence tags'), which costs more than the words saved.

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 5-parameter mutation with zero schema descriptions, the description covers most of what an agent needs, and an output schema exists so return values need not be spelled out. Gaps remain: the unmentioned required model_id and the imprecise encoding of the answers/items payloads.

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 0%, so the description must carry the parameter burden. It explains answers and items by field name with illustrative examples, and says where profile_id and version come from, but the exact encoding of the string arrays (field name + value format) is never specified and the required model_id parameter is not mentioned at all.

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 first sentence states a specific verb and resource: confirming a target's stored profile values as customer-sourced without altering them. It is distinguishable from get_target_profile (referenced as the source of ids) and update_target_profile, though the latter is never named, so the boundary between 'confirm' and 'update' is left implicit.

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?

States clear preconditions: ids must come from get_target_profile, a write scope is required, and only customer-written/confirmed values count as evidence while auto-discovered values do not. It gives no explicit when-not guidance or a named alternative for changing values rather than confirming them.

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 annotations, the description discloses probe behavior, discovery polling, conditional saving, categorized errors, permission requirements, and the fact that the response never echoes config. This is unusually rich behavioral context for a write 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?

The description is front-loaded and every sentence carries useful information, but the long branching sentence for the three input modes is dense and could be easier to scan. It remains appropriately sized for a multi-mode registration 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?

Given the complex conditional workflow, the output schema, and full schema coverage, the description is complete enough to call correctly. It covers workflow entry points, failure behavior, permissions, follow-up tools, and why no credentials are accepted.

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?

Although schema coverage is 100%, the description adds critical cross-parameter semantics: exactly one of config/url/discovery_token, plus needing 'candidate' only when discovery lists multiple candidates. It also explains the required name relationship and the conditional role of url versus config.

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: 'Register an agent ... as a target for security assessments.' It also names sibling tools such as list_targets, get_setup_guide, get_target_discovery, and get_target_profile, making its role distinct.

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 explicit branching guidance for the three mutually exclusive inputs: 'config', 'url', or 'discovery_token'. It also names alternatives and prerequisites directly, including 'Call get_setup_guide first' and 'Check list_targets first'.

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 this a safe, idempotent read, so the description only needs to add behavior beyond that. It does: it discloses the possible run states and the non-obvious conditional that the pass/fail verdict only materializes once the run is terminal. Polling semantics and whether findings are partial/paginated are left implicit.

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 what is returned and followed by the one conditional parameter behavior. No filler and nothing redundant with the annotations.

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 an output schema present, return-value detail is unnecessary, and the description covers states and the conditional verdict well. It omits how a run_id is obtained (list_runs) and whether findings arrive incrementally, which would help an agent polling this tool.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it does for min_severity: it enumerates the allowed levels and explains the functional effect (adds a pass/fail verdict, only when terminal). run_id is left unstated, though its meaning is largely self-evident from context.

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 (fetch) and resource (status of one assessment run), then enumerates exactly what is returned: state values, findings so far, and phase progress. This cleanly separates it from siblings like list_runs (all runs) and cancel_run (mutation) without needing to 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?

Gives clear operational context: fetch status for a single run, and supply min_severity only if a pass/fail verdict is wanted. It does not explicitly route the agent away from alternatives (e.g., list_runs to discover run_id, cancel_run to abort), so it stops short of full when/when-not 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?

Goes well past the annotations: it discloses that redaction is an entitlement limit rather than an empty result, that severity remains accurate while text fields become '[redacted]', and that the transcript is adversarial content requiring [UNTRUSTED:<id>] fencing. It also states the required read scope, which the readOnlyHint alone does not 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?

Front-loads what is returned, then the redaction edge case, then the labeled SAFETY block — good ordering with no filler. The redaction sentence is long and packs several facts, which keeps it from being maximally scannable, but every clause carries real 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?

An output schema exists so return values need no explanation, and the description still covers the two things that could mislead an agent: entitlement-based redaction and untrusted-content handling. Nothing needed to call this correctly on a security 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 single finding_id parameter has 0% schema description coverage and the description never explains its format or origin (e.g., obtained from list_findings). The name is self-explanatory enough that this is a minor gap rather than a blocking one.

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 ('Fetch one finding in full') and enumerates exactly what comes back (technique, severity, status, attack transcript), which cleanly separates it from the list_findings sibling. An agent knows immediately this is the single-record detail call.

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?

Frames the use case explicitly ('so you can diagnose and fix the vulnerability') and, importantly, tells the agent that retrying will not change a redacted result — a real usage constraint. It does not, however, name list_findings as the alternative for browsing or say where a finding_id comes from.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context: the guide content is generated from the live schema and requires the read scope, though it does not discuss response size or formatting beyond the output 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 a single dense sentence that front-loads the primary purpose before enumerating contents. It is appropriately sized for a guide tool, though the long enumeration is slightly run-on and could be structured more scannably.

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 an output schema present, the description need not explain return values. It covers purpose, contents, prerequisite scope, and when to use it, which is complete for a zero-parameter documentation 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 tool has zero parameters, so the baseline is 4 per the rubric. The description does not need to explain parameter syntax and appropriately focuses on the guide contents instead.

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 exactly what the tool returns: a setup guide covering the create_target workflow, config reference, schema-unexpressible semantics, and worked examples. It clearly names the resource and scope, and references create_target, distinguishing it from sibling mutation/list 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?

It explicitly says 'Read this before your first create_target' and states the read-scope requirement. This gives the agent a clear when-to-use trigger and a prerequisite, with no ambiguity about alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the baseline is low, but the description adds real behavior: the returned stage, per-candidate is_proven and has_reply_fetch flags, a job-level needs_session_bootstrap, the guarantee that no credential value is ever returned, and the required read scope. These go beyond annotations and beyond what an agent could infer.

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

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

Four sentences, all information-bearing, with the core action (poll) and prerequisite front-loaded and the security/scope caveats placed last. Slightly dense and packs return-field names mid-sentence, keeping it just short of maximally clean.

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 polling tool with an output schema, the description covers the workflow entry, exit (confirmation), return semantics in brief, security expectations, and auth scope. Nothing an agent needs in order 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?

There is one parameter (discovery_token) with 0% schema description coverage, so the schema itself provides no semantics. The description implies the token comes from the create_target(url=…) call and is reused when confirming, which gives partial meaning, but never states format, lifetime, or whether an expired token errors.

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 (poll) and a specific resource (the discovery job started by create_target(url=…)), plus what it returns (stage, candidate agent calls). It is clearly distinguishable from siblings like get_target_profile or get_assessment_status because it names the originating call that creates the 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?

Gives the precondition that a create_target(url=…) call must have started the job, and spells out the follow-up action (call create_target with discovery_token and optional 'candidate' index). It does not say when not to use it or how to handle a job that never completes / is cancelled, but the routing to the next tool is 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?

Beyond the annotations, the description discloses critical behavioral details: all text values are fenced as untrusted data and must never be treated as instructions, every item carries provenance, the tool requires the read scope, and it returns null when no profile exists. These additions materially reduce ambiguity for a security-sensitive read 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?

The description is dense but front-loaded: it first names what is read, then covers provenance, untrusted fencing, return values, and scope requirements. Every sentence adds operational value, with no filler.

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

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

The description is strong on security semantics, return handoff, and the no-profile case, and the output schema exists so return values need not be fully explained. The only notable gap is the undocumented model_id parameter, which leaves an agent without explicit parameter meaning.

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 0% description coverage for the single required parameter, model_id, and the description never explains what model_id represents or how it relates to the target profile. With low schema coverage, the description needed to compensate but 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: reading a target's profile, with an explicit enumeration of what the profile contains. It also names update_target_profile and confirm_target_profile, making the tool's role in the workflow distinguishable 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?

It clearly implies when to use the tool by explaining that the returned profile_id and version are passed to update_target_profile and confirm_target_profile, and what happens when no profile exists. It does not explicitly exclude or compare against alternatives such as get_target_discovery, so it falls short of full when/when-not 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 declare readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds real behavioral context beyond that: it requires the read scope and refuses trial workspaces on the platform plan. It doesn't discuss result volume or shape, but the output schema covers the return payload.

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 purpose comes first, then the actionable guidance and constraints. No filler, and the most important routing advice 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?

With only one optional parameter, full annotations, and an output schema that documents the return value, the description covers everything an agent needs: what it returns conceptually, when to call it, and the access preconditions. Nothing material 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 reported as 0% and the description never mentions the optional 'lens' parameter or its security/safety/compliance variants. The information exists in the schema's $defs, so an agent can recover it, but the description does no work to explain that the listing can be narrowed to a taxonomy lens.

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 the security categories an assessment run can be focused on') and even clarifies the payload ('each with a description of what it tests for'). It is clearly distinguishable from siblings like list_findings or list_runs by naming the category concept and its consumer, trigger_assessment.

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 says when to use it ('before calling trigger_assessment, instead of guessing keys') and names the alternative behavior it replaces. It also states the consequence of ignoring it: unknown keys are rejected by trigger_assessment, which makes the routing decision 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 establish that this is a read-only, idempotent, non-destructive operation, but the description adds substantial context beyond that. It discloses the redaction behavior on plans that withhold proof, notes that the finding and severity remain real even when category reads '[redacted]', and explains pagination with total_matched and next_cursor bound to the same filters.

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 front-loaded with the core action and ordering, then moves efficiently through filtering, summary-vs-detail routing, redaction behavior, and pagination. Every sentence adds practical information for invoking the tool correctly.

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 existence of an output schema and the read-only annotations, the description supplies everything an agent needs beyond structured fields: filtering semantics, get_finding routing, redaction caveat, and cursor handling. No material invocation detail 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 0%, so the description must compensate, and it largely does: it explains status, target model, minimum severity, specific run filtering, 200-per-page pagination, and the cursor's binding to the original filters. It does not enumerate the allowed status or severity values, though the schema enums do provide those separately.

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 security/safety findings"), names the scope ("your workspace"), and specifies ordering ("most recent first"). It also distinguishes the tool from its sibling get_finding by saying the list returns a compact summary while get_finding returns repro detail.

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 explicitly routes the agent: use this tool for the list, and call get_finding when reproduction detail for a specific finding is needed. It also explains the optional filters and how to continue pagination with the same filters, leaving little to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-structured behavior: ordering (most recent first), an enforced result cap, and the 'truncated' flag to detect clipping. Only lacking is what happens past the cap (no offset/cursor mentioned).

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 with no waste: purpose and scope first, then filter, then paging caveat. Every clause earns its place.

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

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

Output schema exists so return shape needn't be restated, and the description covers paging/truncation, which the schema wouldn't. Minor gap: it doesn't say how to retrieve results beyond the cap, and model_id's source/origin is unstated.

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 carry the load and largely does: it documents the limit bounds (default 20, max 100 — the max is not in the schema at all) and enumerates status values. model_id is only implied via 'one target model' rather than explicitly named/explained.

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?

Specific verb + resource ('List assessment runs') plus scope ('for one target model') and an explicit ordering ('most recent first'). This distinguishes it cleanly from siblings like get_assessment_status (single status) and list_findings (findings, not runs).

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?

States the scoping requirement (one target model) and the optional status filter with its allowed values, which gives clear context for when to use it. It stops short of naming alternatives (e.g., use get_assessment_status for a single run's progress) or stating exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds context those cannot convey: a result cap (default 50, max 200), the need to check the 'truncated' flag, and the required read scope. That is exactly the kind of value-add the dimension rewards.

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?

Front-loaded with purpose, then chained use-case and duplicate-check guidance in two dense sentences. Every clause earns its place, though the duplicate-check rule packs three conditions into one long sentence that could be split for readability.

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?

Output schema exists so return values need no explanation, and the description still covers the cap, the truncation flag, auth scope, and downstream tool usage. Nothing an agent needs to call this 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 coverage is 0% and the single 'limit' parameter has no description, so the description compensates by stating the default (50) and the maximum (200). It does not explain whether 'truncated' responds to limit specifically, but the essential meaning is conveyed.

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?

Specific verb + resource ('List the targets registered in your workspace') with clarifying scope: agents and MCP servers, including what each row carries (latest run status, endpoint_host). It is immediately distinguishable from create_target, list_runs, and the profile tools in the sibling 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?

Explicitly routes to alternatives: use the returned model_id with trigger_assessment or list_runs, and use this as the duplicate check before create_target. It even specifies the matching rule (same name + endpoint_host in same environment = same target; partial match = ask the user), leaving nothing 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?

The description adds real context beyond the annotations: the write scope requirement and the effect on subsequent assessments. However, with destructiveHint=true set, it never clarifies what is actually destroyed or whether the removal is reversible, and the sentence 'The finding itself stays dismissed; only dismissing a finding adds an entry' muddles rather than clarifies the mutation's impact.

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 purpose is front-loaded and the total length is appropriately short. But the middle sentence about the finding staying dismissed is confusing and arguably redundant, spending words without adding usable information for the caller.

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

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

An output schema exists, so the return-value sentence is supplementary rather than necessary. For a destructive mutation with two fully undocumented parameters and no named counterpart tool, the description leaves meaningful gaps an agent would need to close before calling it safely.

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% — neither model_id nor finding_id carries any documentation, and the description does not mention either parameter. It is unclear whether model_id is a target profile id or a model identifier, so the description fails to compensate for the coverage gap.

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

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

The description states a specific verb and resource — removing a dismissal entry from a target's profile — which is clearly distinct from siblings like close_finding or update_target_profile. The intent is legible, though the follow-up sentence about the finding staying dismissed partially obscures what is actually being removed.

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 the downstream effect ('so later assessments stop taking it into account'), which implies when to use it. But it never names the counterpart operation that creates a dismissal, nor states when not to call it, leaving the agent to infer the pairing from the schema.

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?

Adds genuine context beyond the annotations: it returns immediately with a run_id, executes in the background, and requires the test:run scope. The requirement to poll get_assessment_status is behavior an agent could not infer. Minor gap: with destructiveHint=true, the description never explains what side effect or persistent artifact a run creates.

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?

Front-loads the core action, then stacks guidance, side effects, and the auth requirement in a logical order with no filler. The e-dash-heavy sentences are dense and slightly long, but every clause adds information an agent needs.

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

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

For a two-param, open-world trigger tool with an output schema, the description covers initiation semantics, async behavior, the follow-up polling tool, category constraints, rejection behavior, and the required scope. Nothing needed 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 coverage is 0%, so the description must carry the load and largely does: it explains that categories are taxonomy keys discovered via list_categories, that they are agent-only and rejected as invalid_argument if out of scope. It leaves model_id's format (which target identifier) implicit, relying on the phrase 'one of your targets'.

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 ('trigger a security assessment run') and scopes it to 'one of your targets, an agent or an MCP server'. An agent can immediately tell what the tool does and what it operates on, and can distinguish it from the read-side siblings like get_assessment_status or list_runs.

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 says to call list_categories to discover valid keys, that an out-of-lens key is rejected as invalid_argument, that MCP server runs take no categories, and to poll get_assessment_status afterward. Covers when to use, how to prepare, and what to do next.

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

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

Goes well beyond the annotations (destructive, idempotent, non-readOnly): it discloses that omitted fields are untouched, null clearing rules per field, whole-list replacement, ownership transfer to the customer, immediate application, history attribution, rejection of [UNTRUSTED:…] values, and the write scope requirement. These are exactly the mutation-side effects an agent needs.

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

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

Front-loaded with the core action and the `changes` example before edge cases. It is a dense single block, though, with null rules, list replacement, fence handling and versioning packed together with no grouping, which makes it slower to scan than it could be.

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

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

For a destructive, nested-object mutation tool, it covers semantics, prerequisites, creation path, validation rejections and the return value ('Returns the profile's id and new version'), so an output schema's presence is complemented rather than required.

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%, but the description compensates heavily: it defines the three parameter groups (profile_id, version, model_id, changes), explains omission vs null per field, defines the {name, description, parameters} tool shape and {name, auth_level, description} user-type shape, and requires turning tool parameters into an object. This adds meaning the schema alone does not convey.

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 ('Change content fields of a target's profile by name') and immediately scopes behavior to the `changes` object. It is clearly distinguishable from get_target_profile (read) and confirm_target_profile (approve) by its mutation semantics and its note that omitting ids creates a profile for a target that has none.

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

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

Gives concrete usage instructions: pass profile_id and version from get_target_profile, or leave both out to create a profile for a target that lacks one. It also states prerequisites ('Requires the write scope'). It does not explicitly name sibling alternatives or when-not-to-use, so it stops short of a 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?

Adds substantial context beyond annotations: attacks run against a live target, the test:run scope is required, results are asynchronous ('validating'), and 'still_broken' can mean the re-run could not confirm the fix. These details materially affect safe invocation of a destructive/open-world 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 tightly written sentences: the first states the action, the second enumerates verdicts and the polling fallback. Every clause adds operational value with no repetition.

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

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

Covers action, preconditions, auth scope, possible outcomes, and async polling. Although an output schema exists, the verdict enumeration is useful because it tells the agent how to interpret and act on 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?

With one required parameter and 0% schema description coverage, the description implies finding_id identifies the finding whose attacks are re-run. However, it does not define the expected ID format or otherwise enrich the parameter beyond its obvious meaning.

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: re-run a finding's attacks against the live target to confirm a fix. The verdict list makes the outcome unambiguous and distinguishes it from siblings like get_finding or close_finding.

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: use after marking a finding fixed, and re-read status with get_finding while validating. It does describe prerequisites, but does not explicitly name close_finding or other alternatives and when not to use this tool.

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