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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the agent knows this is a scoped, repeatable write. The description contributes the ownership constraint and the running-state precondition, but says nothing about whether partial findings are discarded, whether cancellation is immediate, or what the resulting scan state becomes — meaningful gaps for a destructive tool.

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

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

A single front-loaded sentence with zero filler; the verb and resource lead. It is arguably under-specified rather than padded, but 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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. Still, for a destructive operation the definition omits how to obtain the session id, what state the scan ends in, and whether partial results survive — gaps an agent must resolve by trial.

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% for the single required parameter, and the description never mentions session_id or where the agent obtains it (presumably from vyntryx_scan_source_upload or vyntryx_scan_source_git). With only one parameter this is a small surface, but the description does nothing to compensate for the 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?

States a specific verb and resource ("Cancel a running scan") plus an ownership qualifier ("that you started"), which separates it from the scan-creation siblings. It never names an alternative such as vyntryx_scan_status, so differentiation is inferred rather than stated.

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

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

"running scan that you started" implies both the state precondition and the ownership/auth scope, which is more than nothing. However, there is no explicit when-not guidance (e.g., what to do about completed or failed scans) and no sibling is named as an alternative path.

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 the tool is read-only and closed-world. The description adds useful behavioral context by disclosing that AI-suggested impact is explicitly labelled, which helps an agent interpret provenance and reliability.

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 redundant content. Every clause contributes to explaining the relationship scope or the impact-labelling behavior.

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 description need not document return values, and annotations cover the read-only safety profile. The remaining description is sufficient for a simple one-parameter relationship lookup, though it could clarify relationship direction or types.

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 for the undocumented uuid parameter. It only refers to 'this one' without naming the UUID, explaining its format, or clarifying whether it is a finding identifier; the meaning is inferable but weakly specified.

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 resource and output: findings linked to a given finding plus potential impact of fixing it. It does not explicitly distinguish this from siblings like vyntryx_get_finding or vyntryx_list_findings, but the relationship-focused purpose is still clear.

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

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

Usage is implied by the phrase 'Findings linked to this one and what fixing it may affect,' suggesting it should be used for relationship or impact exploration. However, there is no explicit guidance on when to use this versus vyntryx_get_finding or other 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful fact that this is the detail-expansion step after listing, but says nothing about auth requirements or failure behavior when a uuid is unknown.

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, front-loaded with the return payload and closed with the parameter provenance. Nothing is wasted.

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

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

With an output schema present, the description needn't explain return values, and the read-only nature is annotated. The remaining gap is minor: no note on what happens if the finding ID is stale or from another session.

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 carries the burden, and it does supply the key provenance for both parameters (both come from vyntryx_list_findings). It gives no format detail for the UUID or session_id, so an agent still cannot validate inputs without trial.

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 resource (one finding) and the payload returned (full detail, evidence, remediation), which clearly separates it from the list-oriented sibling. It stops short of an explicit verb like 'retrieve', but the intent 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?

It implicitly routes the agent: get the session_id and uuid from vyntryx_list_findings, then call this tool. That's a clear precondition, though there is no explicit 'do not use this to browse' exclusion or guidance on error cases.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that results are scoped to a session and carry CWE/file:line metadata, but says nothing about result limits, ordering, or behavior on a stale/invalid session — useful gaps remain given an output schema 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?

Two sentences, no filler, with the core scope front-loaded and filters trailing. The opening is a noun fragment rather than a clause, which costs a little clarity for the sake of brevity.

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 format needn't be spelled out, and the read-only nature is covered by annotations. Still missing are the status filter's valid values, any result-count/pagination behavior, and error handling for an invalid session — reasonable expectations for a filterable list 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 0%, so the description must carry the load. It does add real value by enumerating severity values (critical|high|medium|low|info), which the schema does not since there are no enums, but it leaves status as an unqualified string with no allowed values and only implicitly explains session_id as the scan session UUID.

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 resource (findings) and scopes it to a scan session, and enumerates the returned fields (UUID, title, severity, file:line, CWE), which makes clear this is a bulk listing versus the singular vyntryx_get_finding. It never uses an explicit verb like 'list', so the plural/collection nature is inferred from the field list rather than stated.

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

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

'Optional filters' implies this is the browsing call you use when you want many findings, but the description never says when to prefer it over vyntryx_get_finding or vyntryx_finding_relationships, nor what happens if session_id is unknown. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds the meaningful extra context that a negative result is an expected outcome requiring an out-of-band terminal login, which tells the agent not to treat it as an error. It does not mention the return payload's shape, but an output schema exists to cover that.

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

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

Two short sentences, front-loaded with what is returned and followed by the only branch that matters (not logged in). Nothing is redundant with the name, schema, or 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?

For a zero-parameter read with annotations and an output schema, the description covers purpose, failure mode, and remediation. The only omission is any hint about ordering relative to the scan tools, which would have made it 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 tool takes zero parameters, so the baseline is 4; there is no parameter surface for the description to clarify or neglect.

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 ('Show whether this connector is logged in to Vyntryx, and as whom'), going beyond the name to say that identity as well as boolean state is returned. No sibling tool does authentication inspection, so the boundary 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 supplies an actionable remediation path ('the user must run `vyntryx-mcp login` in a terminal') but never states when an agent should call this versus proceeding straight to scan/finding tools, nor that it should be checked before other operations that require auth. Usage is implied by the logged-out branch 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 declare this is a non-read-only, non-destructive, non-idempotent, closed-world write, so the safety profile is covered. The description usefully adds that the message becomes visible in the Vyntryx UI, but says nothing about persistence, whether the session must be live, or broadcast semantics for other users.

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

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

A single front-loaded sentence with the verb and target stated first and zero padding. It is efficient but leaves obvious room to add the missing session_id and lifecycle context without becoming bloated.

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 and annotations cover the mutation profile, so return values and safety need no explanation. However, with two required parameters at 0% schema coverage and no guidance on session lifecycle or where session_id comes from, an agent still lacks information needed to invoke it confidently.

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

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

Schema description coverage is 0% and both properties are bare titles, so the description must compensate and largely does not. 'text' is inferable from 'Post a message', but session_id is never explained — not where to obtain it (e.g., from vyntryx_scan_status) nor what happens if it is invalid.

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

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

States a specific verb+resource+target: posting a message into a scan session's chat, and adds the observable effect that it appears in the Vyntryx UI. It is distinguishable from the read-side sibling vyntryx_session_messages by implication, but never names it or any sibling explicitly.

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

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

Usage is only implied by the description ('into a scan session's chat'), with no statement of when to prefer this over vyntryx_session_messages or other tools, and no prerequisites such as needing an active session or authentication.

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

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

Annotations already declare non-readonly, open-world, non-idempotent, non-destructive behavior, so the bar is lower. The description adds genuinely useful context beyond that: the token is sent once and never stored or shown, and a scan is started as a side effect. It does not say whether the scan is async or how progress is tracked.

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 primary action first, then the conditional private-repo guidance. Every clause carries information an agent needs (ref semantics, token_env format, storage guarantee).

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

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

An output schema exists, so return values need not be explained. The remaining gap is lifecycle context: that a scan is started asynchronously and that vyntryx_scan_status is the way to follow it, plus that `url` must be an https git URL.

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 carries the full burden, and it explains both non-obvious params: `ref` as branch/tag/commit and `token_env` as the NAME of an env var with the required VYNTRYX_GIT_TOKEN prefix. Only `url` is left implicit (https git URL), which is a minor gap against a full compensation.

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

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

States a specific verb+resource ('clone a git repository over https ... and start a SAST/SCA/secrets scan'), which clearly separates it from the upload-based sibling and the login/status tools. It stops short of naming the alternative explicitly, but the purpose is unambiguous.

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

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

Gives a concrete usage condition for private repos ('pass token_env'), which is more than most definitions offer. It never states when to prefer this over vyntryx_scan_source_upload (local files/archives) or what the https-only constraint excludes.

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

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

Annotations already declare non-read-only, open-world, non-idempotent, non-destructive, so the description is not carrying the safety burden alone. It still adds real value by spelling out exactly what is stripped from the package (secrets, .gitignore'd files, .git, dependencies, build output), which an agent could not infer from the annotations and which materially affects what gets scanned. It omits that repeated calls create separate scan sessions (idempotentHint=false) and any size/time limits.

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

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

Two sentences, zero filler, with the action and the exclusion semantics front-loaded and the return value last. Every clause carries information.

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

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

The output schema means return values need no further explanation, and the core action is well covered. But for a tool that uploads local code off-machine and kicks off a scan, the description says nothing about authentication requirements, whether the uploaded package is retained, or how the exclusion parameter composes with defaults.

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% across three parameters, so the description must compensate and largely does not. It gestures at exclusion behavior, but never explains whether the `exclude` array is additive to the built-in defaults or replaces them, and the `name` parameter is never mentioned at all, leaving the agent to guess at its effect.

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 three specific verbs (package, upload, start scan) against a clearly scoped resource: a local project folder. The word 'local' implicitly separates it from vyntryx_scan_source_git, and the scan types (SAST/SCA/secrets) plus the return value (scan session id) are stated outright.

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 stated: 'local project folder' suggests this is the path-based alternative to the git-based sibling, but neither the sibling nor the either/or condition is named. There is no mention of prerequisites such as an authenticated session (vyntryx_login_status) or of what to do when the source lives in a remote repo.

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=false, so the safety profile is covered, but the description adds nothing beyond them. It does not say whether the call is cheap to poll, what states exist, whether a session can expire or be cancelled out from under it, or how progress is reported.

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 short, front-loaded sentence with no filler. It is efficient, though the terseness is part of why other dimensions are weak.

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, but the definition still omits the session_id origin, polling expectations, and the scan lifecycle context that would let an agent use this correctly within the vyntryx scan workflow.

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% for the single required parameter session_id, and the description never mentions it or explains where the identifier comes from (presumably an upload/git scan call). With one undocumented required parameter, the description needed to compensate and does not.

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

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

The phrase 'State and progress of a scan session' identifies the resource (a scan session) and the kind of information returned (status/progress), which does separate it from siblings like vyntryx_cancel_scan or vyntryx_list_findings. However it is a bare noun fragment with no verb, so the agent must infer that this is a retrieval operation rather than a state change.

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 call this versus vyntryx_session_messages, vyntryx_cancel_scan, or the login/source tools, and no indication of whether it should be polled or called once. Usage is only implied by the word 'status'.

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=false, so the safety profile is covered. The description adds useful context that these are chat messages 'what the Vyntryx UI shows' and that `since` enables incremental retrieval, but it does not disclose ordering, pagination, or volume behavior beyond that.

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 redundant or filler content. The optional filtering behavior is attached directly to the resource being described.

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 read tool with annotations and an output schema, the description is largely complete: it identifies the resource and explains the incremental filter. Minor gaps remain around session_id semantics and message ordering, but the output schema can carry return-value details.

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 parameter meaning. It explains `since` well as an id or timestamp from an earlier call, but does not explain `session_id` beyond its name, leaving one of two parameters only self-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 clearly states that the tool retrieves chat messages for a scan session, which is a specific verb implied by the resource and distinct from the write-oriented sibling vyntryx_post_message. It does not explicitly name or contrast with that sibling, so it falls just 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 implies usage by identifying the resource and explaining the optional `since` filter for incremental fetches. However, it does not state when to use this tool versus alternatives such as vyntryx_post_message or other session-related tools, nor does it give exclusions or prerequisites.

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