72hours security check

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

Goes well beyond the annotations (readOnly=false, openWorld=true, idempotent=false): it discloses workspace creation side effects, the token secrecy requirement, a 90-second wait bound, GPU analysis of the top 0-5 findings, and a summary + next-steps return. These are exactly the operational facts an agent needs before committing to a long, non-idempotent call.

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 compact block with the core action first, then preconditions, side effects, timing bound, and parameter rules. No filler sentences, and each clause carries distinct operational 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 5-parameter, no-output-schema, open-world orchestration tool, this covers timing, side effects, and idempotency well. It stops short of describing failure/timeout behavior after the 90-second wait or what happens if the repo is private, which would matter for a blocking 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?

With 0% schema coverage the description must carry the load, and it does for most parameters: workspace_token (empty means create), max_analyses (0-5, controls GPU analysis breadth), request_id (same-request reuse only), and repository_url scope. The `authorized` boolean is only obliquely implied by 'user is authorized to scan' and never explicitly tied to a parameter value.

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 ('One call security audit of a PUBLIC GitHub repo') and scopes it to authorized scans of public repos. The 'one call' framing implicitly distinguishes it from the sibling chain (create_workspace → start_scan → start_analysis → audit_status) it orchestrates.

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 preconditions (public repo, user authorized) and rules (reuse request_id only for the same request, empty workspace_token triggers workspace creation). It doesn't explicitly route to alternatives such as start_scan or audit_status for polling, so the comparison is left to inference.

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

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 behavioral context by indicating it aggregates multiple pieces of information in one call, but it does not discuss return granularity, freshness, or prerequisites beyond the implied scan_id.

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, and it lists the returned information compactly while linking to the related fix-prompt 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?

The tool is simple with two required parameters and no output schema, and annotations already define it as a safe read. The description adequately explains what the tool returns, but it is incomplete on parameter meaning, which matters because both parameters are required and undocumented in the schema.

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

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

Schema description coverage is 0% and both parameters are required, but the description does not explain what workspace_token or scan_id represent or how they should be supplied. It relies entirely on parameter names, leaving a meaningful gap for the agent.

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 the resource and what it returns: scan summary, analysis statuses, and ready fix prompts. It distinguishes itself from get_fix_prompt by saying it reports which fix prompts are ready in one aggregated call, though the verb is implicit rather than explicit.

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 'in one call' implies this is an aggregation/status tool, which gives some usage context. However, it does not explicitly say when to prefer this over get_analysis, get_scan, or get_fix_prompt, nor does it state prerequisites or 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 the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds useful behavioral context about when to call it and how to interpret an unchanged commit, but it does not explain the side effects of triggering a rescan or why the operation is not idempotent.

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 prerequisite condition, and no wasted words. The output categories and the commit caveat are both stated 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?

Covers the purpose, output categories, and an important commit-state caveat, but leaves three of four parameters undocumented and does not clarify the non-readonly rescan side effects. With no output schema and no parameter descriptions, it is only minimally 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 0% across four parameters, but the description only explains scan_id. It leaves workspace_token, request_id, and authorized undocumented, so it does not 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?

States a specific verb and resource: rescans the same repo against scan_id and lists finding categories. However, it does not differentiate this tool from the sibling rescan tool, so it falls short of a 5.

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

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

Gives a clear usage condition: after fixes are pushed to the default branch. It also explains the diagnostic case where the same commit means the fix was not pushed, though it does not name explicit alternatives or 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 destructiveHint=true and readOnlyHint=false, so the description's added value is the disclosure that result access is revoked while backend jobs keep running. That is genuine non-obvious behavioral context an agent could not infer from the annotations, though permanence/irreversibility of the revocation is not stated.

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

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

Two short sentences with the action front-loaded and the important caveat immediately after. Nothing is padded and nothing repeated from the title 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 destructive single-parameter tool with no output schema, the description covers the main side effect and its key exception, which is adequate at a minimum. It still leaves open whether revocation is permanent, what happens to stored results, and how the token is sourced, which an agent needs before calling a destructive 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% for the single required parameter workspace_token, and the description only refers vaguely to 'this workspace'. It does not say what the token is, where an agent obtains it, or whether it identifies an active session, leaving the sole parameter 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?

States a specific verb ('Revoke') and resource ('workspace') plus the scope of what is revoked ('its result access'), which clearly positions it as the inverse of create_workspace. It stops short of explicitly naming sibling tools or contrasting with non-destructive reads like get_analysis.

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 a useful negative condition ('Does not cancel already submitted backend jobs'), which tells the agent this is not a job-cancellation tool. However, there is no positive guidance about when to close a workspace, no prerequisites, and no named alternative for job 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?

Annotations already indicate a non-readonly, open-world, non-idempotent creation operation. The description adds valuable behavioral context beyond that: the workspace is private and expiring, and its capability is sensitive enough to be saved only in the user's AI conversation. It still omits expiry behavior and capability 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?

Two short sentences with no wasted language. The core action is front-loaded, and the capability-handling instruction follows immediately.

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?

No output schema exists, so the description should carry more of the return-value burden. It mentions the 'capability' but does not define its format, explain workspace expiry duration, or clarify how the workspace is used with sibling tools, leaving meaningful gaps for an agent.

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 parameter-semantics baseline is 4. The description adds a useful hint that the result includes a 'capability' to preserve, but there are no parameters 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 verb and resource: 'Create a private, expiring workspace.' The qualifiers 'private' and 'expiring' add meaningful scope, but it does not explicitly distinguish this from close_workspace or explain how the workspace relates to sibling 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 gives a security-handling instruction ('Save its capability only in the user's AI conversation') but says nothing about when to create a workspace instead of using other tools, nor when not to use it. There is no explicit alternative or lifecycle 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely useful context that the report tolerates 'available' (partial) analyses and flags incomplete work as such. It still omits what happens when scan_id doesn't exist or isn't owned, and what the report contains.

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 dense sentence with the action front-loaded and no filler. It is slightly overloaded (three ideas packed into one clause chain) but nothing is wasted.

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

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

With no output schema, the description should convey what the report actually is/returns, and it does not. For a two-required-parameter tool it also leaves both parameters unexplained and gives no behavioral boundary for partial or failed input, so an agent can construct the call but not predict the result.

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 two required parameters. The description only obliquely gestures at them — 'owned server scan' hints scan_id refers to a scan the caller owns, and that ownership is enforced — but workspace_token is never mentioned and no format, source, or constraint is given for either.

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: 'Generate the service's report', with a stated input basis ('owned server scan and available analyses') and a stated characteristic ('indicating incomplete work'). However, 'report' is not clearly separated from the sibling 'incident_report', nor from 'get_scan'/'get_analysis' whose outputs feed it, so the agent must guess the boundary.

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

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

No when-to-use guidance, no prerequisites (must a scan exist? must analyses finish?), and no mention of alternatives such as incident_report or audit_status. The clause 'indicating incomplete work' hints the report is safe to run before analyses finish, but that must be inferred 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds latency ('inference can take several minutes') and a strong behavioral warning ('Never fake ready results'), but omits auth needs, rate limits, or error handling details.

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 main action, and no filler. The second sentence is a clear directive. Slightly under-specified rather than verbose.

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

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

For a simple read-only polling tool with annotations covering safety, the description covers what it does and a key behavioral caveat. However, it leaves parameter meaning, return-value expectations, and relationship to start_analysis unexplained, which an agent would need for reliable 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% for both required parameters (workspace_token, analysis_id), and the description does not mention them at all. The agent receives no semantic guidance on what these fields expect or how to obtain 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 says 'Poll GPU status and delivery gates', which gives a verb and some objects, but it never states that it retrieves analysis results or how it differs from start_analysis. An agent can infer it is a status-checking tool but cannot confidently distinguish its purpose 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 phrase 'Poll GPU status' implies repeated checking, but there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives (e.g., start_analysis, get_scan). The warning 'Never fake ready results' is a behavioral rule, not usage routing.

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

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

Annotations already declare this as read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds that the proposal is "gated" and tied to an agent workflow, but it never explains what gating means, whether authentication is required, or what the agent 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 only two sentences and front-loads the supposed action before giving workflow constraints. It is compact, though the opening phrase is jargon-heavy rather than precise.

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, but the two required parameters remain opaque and the gated workflow is not elaborated. For a tool that apparently coordinates code inspection, repo/commit checks, fixes, and tests, the description leaves too much unresolved.

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 required parameters, workspace_token and analysis_id, are undocumented in the schema. The description mentions a workspace only generically and adds no meaning for analysis_id, so it does not 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 phrase "Get a gated real LLM proposal" is vague and does not clearly explain what a fix prompt is or how it differs from siblings such as check_fix or get_analysis. The second sentence describes an agent workflow rather than the tool's actual output.

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?

"Agent must inspect code, check repo/commit, fix and test in its workspace" gives prerequisite-like instructions, but it does not say when to call this tool versus alternatives or what conditions select it. No exclusions or sibling routing are 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?

Annotations already establish that this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond that: the required poll interval and the fact that results include the actual commit, coverage, and up to 50 findings.

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 efficient sentence with no filler, and the polling cadence is front-loaded. Its telegraphic style makes it slightly cryptic, but every phrase 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 simple read-only polling tool with no output schema, the description does explain the key return fields and polling interval. However, it omits all parameter semantics, which is a meaningful gap given 0% schema description coverage.

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 required parameters (workspace_token and scan_id) are undocumented in the schema. The description does not compensate by explaining either parameter's meaning or format, leaving the agent with almost no parameter guidance.

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 communicates a specific operation: poll a scan and return commit, coverage, and up to 50 LLM-input findings when complete. It distinguishes this polling behavior from sibling actions like start_scan or rescan, though it never explicitly labels the resource as 'scan status.'

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 clear usage context with the polling cadence ('Poll every >=10 seconds'), which tells the agent when and how often to call it. It does not name alternatives or exclusions, such as when to use get_analysis instead.

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, and the description reinforces this with 'Draft only; NEVER submits' — a meaningful clarification that the tool writes nothing externally even though it constructs an incident record. The added constraint 'Use only user-confirmed facts' is a genuine behavioral rule an agent could otherwise violate; what's missing is any note about persistence of the draft or prerequisite state of scan_id.

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 highest-value fact (draft-only, never submits), then a compact field map. It is dense and slightly run-on in the incident field enumeration, but no sentence is filler given the zero schema coverage.

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

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

For a 4-parameter tool with a deep nested incident object, no output schema and 0% schema coverage, the description supplies enough structure for a correct call. Gaps remain on return value (what a 'draft' looks like back) and on the identity/authorization parameters, but nothing essential to constructing the payload is absent.

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

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

Schema description coverage is 0%, so the description carries the full burden and largely delivers: it spells out the kind values (which the schema lacks an enum for), the required discovered_at ISO time, and the nested organization / personal_info field shapes including the leaked enum. It leaves workspace_token and scan_id undocumented, which keeps it from a 5.

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 conveys a specific resource (an incident/compliance report) and an explicit scope restriction ('Draft only; NEVER submits'), and enumerates the three report kinds (assess / incident-24h / privacy-72h) that define what the tool produces. It stops short of naming the sibling it differs from (generate_report), so an agent must infer the boundary, but the purpose itself 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?

'Draft only; NEVER submits' and 'Use only user-confirmed facts' give useful operating constraints, and the kind values imply the triggering scenario (24h/72h regulatory clocks). However, there is no explicit statement of when to choose this over generate_report or when the tool should be avoided, leaving routing 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?

Adds genuine context beyond annotations: the scan reads the remote default branch, so local unpushed edits are invisible — important for interpreting results. Annotations already cover the safety profile (destructiveHint=false, openWorldHint=true), but the description does not explain that each call launches a new, non-idempotent scan job or what it returns.

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 the core action and followed by the most decision-relevant caveat. No filler, though the terseness leaves no room for the prerequisite and return-value 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 tool that triggers a new non-idempotent scan with three required parameters and no output schema, the description omits what it returns (a new scan id?), whether the operation is async, and how previous_scan_id / request_id are used. Substantial gaps remain.

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 4 parameters, and the description names none of them. 'SAME repository' hints that previous_scan_id anchors the target, but workspace_token and request_id are left entirely unexplained in both schema and description.

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

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

States a specific verb (rescan) and a specific resource scope (the SAME repository default branch), with 'SAME' signaling it reuses an existing repository context rather than picking a new one. This implicitly distinguishes it from start_scan, though that sibling is never named.

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 'Only published changes are visible; unpushed edits are not' implies when a rescan is worthwhile (after changes are pushed), but there is no explicit when-to-use, no when-not, and no mention of start_scan as the alternative for a different repository.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered structurally. The description adds that the call is preparatory/informational, but says nothing about output shape or volume, which matters since no 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?

A single short sentence with the timing cue placed where it matters. It is efficient, though "the whole workflow" is loose phrasing that could have been tightened into a concrete statement of contents.

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

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

For a zero-parameter, read-only discovery tool with no output schema, the description should tell the agent what it will actually receive (workflow steps, capability list, limits). It gestures at this but leaves the return contents undefined, which is the main remaining 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?

The tool takes zero parameters and the schema is empty, so there is nothing for the description to clarify. Baseline 4 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?

"Learn the whole workflow and available service capabilities" indicates an informational/discovery tool, which is distinct from action-oriented siblings like start_scan or create_workspace. However, "learn" is a soft verb and the description never states concretely what the tool returns (workflow steps, capability list, or both), so the purpose stays somewhat vague.

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 "before creating work" gives an implied ordering hint — call this ahead of the create/start siblings. There is no explicit when-not guidance and no named alternative, so the routing signal is suggestive rather than directive.

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

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

Annotations already declare the safety profile (non-read-only, open-world, non-destructive), so the description's added "Same inputs deduplicate" is a genuine behavioral fact. However, it says nothing about the async/long-running nature implied by "GPU" work, whether an analysis ID is returned for polling via get_analysis, or cost/quota effects — the details an agent most needs here. There is also mild tension between the dedupe promise and idempotentHint=false.

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

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

Two short sentences with no filler, and the action plus scope are front-loaded before the dedupe caveat. Nothing extraneous, but nothing especially well-structured either.

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

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

There is no output schema, yet the description never says what comes back (an analysis handle? a status?) or how to follow up on a GPU job that finishes later. For a three-required-param, open-world initiation tool, that leaves the calling agent guessing about the end-to-end 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%, so all three parameters (workspace_token, scan_id, fingerprint) are undifferentiated strings. The description only hints that scan_id and fingerprint jointly identify "one real scan finding" and never explains workspace_token at all, so it fails to compensate for the coverage gap.

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

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

Specific verb ("Start") plus a scoped resource ("GPU Red/Blue review of one real scan finding"), which separates it from start_scan (whole-scan initiation) and get_analysis (retrieval). The "Red/Blue review" phrasing is domain jargon an outside agent may not decode, keeping it 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?

"One real scan finding" implies a prerequisite (an existing finding from a completed scan) and singles out the per-finding scope, but there is no explicit when-to-use rule, no mention of get_analysis for polling results, and no statement about what to do if an analysis already exists.

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, openWorldHint=true and destructiveHint=false, so the safety profile is known. The description adds a real prerequisite (user authorization) and retry semantics, which is useful beyond the annotations, but it omits that the scan is likely asynchronous and how progress is obtained. Note a mild tension: idempotentHint=false while the description advises reusing request_id for identical retries – it is a dedup-key pattern rather than a true 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 short sentences, front-loaded with the action and the precondition, with no filler. The capitalized 'REAL' is unusual but does convey a meaningful distinction from demo flows.

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 open-world, non-read-only operation with no output schema and no parameter documentation, the description leaves too much out: what is returned (e.g. a scan id), whether execution is async, and which sibling to call next for status. An agent can form the call but not a full 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% across four parameters, so the description must carry the burden and mostly does not. It only clarifies request_id's reuse-for-retries semantics; workspace_token and repository_url are never explained, and 'authorization required' conflicts with the schema where `authorized` is optional with a default of false, leaving ambiguity about whether it must be set.

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 ('Start a REAL public GitHub scan'), and the emphasis on 'REAL' implicitly separates it from demo/verification siblings like verify_demo. It does not explicitly distinguish itself from start_analysis or rescan, which are the closest alternatives.

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

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

'User authorization required' gives one precondition, and 'Reuse request_id on identical retries' gives retry behavior. But there is no guidance on when to choose this over start_analysis, rescan, or audit_repository, so the agent must infer the routing.

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

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

Annotations already state idempotent=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds genuinely new context: execution occurs in an isolated sandbox, attacks are replayed before and after the fix, and repeat calls can poll an existing job via verify_job_id. It stops short of saying what happens to prior runs or the response shape.

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 compact sentences, each contributing distinct information (scope, modes, exclusion, polling) with the most important scoping constraint front-loaded. Slight cost from an awkward line break and the mid-sentence 'Not the user's repo' placement, but 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?

With no output schema, the description still manages to signal a status-bearing result (queued/running) and how to continue polling, which is the key thing an agent needs. Minor gaps remain around job lifecycle (how long polling may take, what a terminal state looks like) for a long-running verification 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?

Schema description coverage is 0%, so the description must carry the load and it largely does: it enumerates the two meaningful values of mode and explains that verify_job_id should be passed when a prior call returned queued/running to continue the same job. The defaults (mode=reference, empty verify_job_id) are only in the schema, and polling cadence/timeouts go unstated.

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?

Starts with a specific verb-and-resource statement ('Runtime proof on the DEMO target') and enumerates exactly what happens (sandbox replay before/after fix plus functional tests). The clause 'Not the user's repo' cleanly separates it from audit_repository and check_fix without requiring a schema lookup.

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 bounds usage ('DEMO target only', 'Not the user's repo') and explains the mode choice as reference (human fix) vs ai (Red/Blue). It also gives a conditional instruction for repeat calls with verify_job_id, though it never names a sibling alternative for the non-demo case by name.

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