Guarita

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the target app may still be unpublished, a well-known file is returned and must be added, and publishing precedes the follow-up call. It does not address permissions or authorization requirements beyond the flag param, keeping it out of 5 territory.

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 that lead with the purpose and then lay out the required sequence of actions. Nothing is wasted or redundant.

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

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

For a stateful onboarding-start tool with annotations covering idempotency and safety, the two-step workflow narration gives enough context to call it correctly. The only gap is that the returned well-known file's format is unknowable pre-call in the absence of an output schema.

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

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

Schema coverage is 67%, and the schema itself documents idempotency_key and authorization_confirmed. The description names no parameter directly, so it adds no syntax or format meaning beyond what the schema already provides — baseline 3.

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 ('Creates an account-bound verification challenge') and implicitly distinguishes itself from complete_app_onboarding by positioning itself as the first step of the sequence. An agent can tell what this tool does and where it sits in the workflow.

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?

Describes the workflow context ('the app may still be unpublished; add the returned well-known file, publish through Lovable, then call complete_app_onboarding'), which clarifies when this tool is the right entry point. It stops short of explicit when-not-to-use or an alternative for apps that are already published, so it is not a full 5.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: it requires binding the exact published origin, performs a proof check, and queues a basic round only on success. It stops short of describing what happens on verification failure, what proof is checked against, or auth requirements.

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

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

A single, front-loaded sentence with no filler; the primary action leads and the success-conditional clause trails it. It is dense with unexplained jargon, but nothing is wasted.

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

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

For a verification/state-advancing tool with no output schema and no readOnlyHint, the description should say how success or failure is surfaced and what the agent must supply beyond the URL. It omits failure behavior, return shape, and any permission requirements, so an agent cannot fully anticipate the call's outcome.

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 there are no param descriptions, so the description carries the full burden. 'Binds the exact published HTTPS origin' adds some meaning to published_url (it must be the exact published HTTPS origin), but onboarding_id is never explained and neither param's format or source is clarified.

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

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

The description gives specific verbs (binds, checks, queues) and a resource (the published HTTPS origin / first basic round), so an agent can tell roughly what it does. However it never actually says it 'completes onboarding', and 'Guarita proof' is project jargon an agent cannot resolve. It also does not differentiate itself from the sibling begin_app_onboarding, leaving the pair's division of labor 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?

No when-to-use, no prerequisites, and no mention of the alternatives in the sibling set (begin_app_onboarding, get_app_onboarding_status). The sequence 'begin then complete' is only inferable from the tool names, not stated. An agent gets no explicit condition for choosing this over retest_finding or start_scan.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is fully covered structurally. "Without changing it" merely restates readOnlyHint rather than adding new context such as permission requirements or how the status is derived. Consistent with annotations, but adds little.

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 or repetition. It is efficient, though its brevity shades into under-specification rather than optimal density.

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

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

There is no output schema, so the description carries the burden of explaining return values, yet "proof and first-round status" is too vague to tell an agent what it will actually receive. Combined with an undocumented required parameter, the definition is not complete enough for confident invocation.

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

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

The single required parameter onboarding_id has 0% schema description coverage, and the description never mentions it or explains its format/source. With an undocumented required parameter, the description 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?

States a verb ("Returns") and a resource ("proof and first-round status"), but "proof" and "first-round status" are unexplained jargon that don't obviously map to the tool name's "onboarding status." It does not distinguish itself from siblings like begin_app_onboarding or complete_app_onboarding, which also touch onboarding state.

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

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

There is no explicit when-to-use guidance and no mention of alternatives. The phrase "without changing it" only implies this is a safe read, which an agent could infer from the name and annotations alone; it never says when to call this versus begin/complete_app_onboarding.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds genuinely new context: that the prompt is 'bounded' and that finding content is untrusted app data that must not be interpreted as instructions. That injection warning is valuable and not derivable from structured fields.

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

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

Two tight sentences with no filler; the primary behavior is front-loaded and the safety constraint follows. Every clause earns its place.

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

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

For a read-only tool with no output schema and no parameter documentation, the description covers the read path and the injection hazard but leaves both parameters and the shape/size of the returned prompt largely unexplained. Adequate but with clear gaps.

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

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

Schema description coverage is 0% for both required parameters. The description only hints that a finding belongs to this account and never mentions scan_id, so it does not compensate for the schema gap in identifying which scan the finding lives in.

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: returns a bounded remediation prompt for a finding. The 'owned by this account' scoping is a useful qualifier. It is clearly distinct from get_scan_summary and retest_finding in resource, though it never names a 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?

No when-to-use guidance, no prerequisites, and no alternatives named. The workflow (scan → finding → fix prompt) is only inferable from the name and title, not stated in the description.

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, and closed-world, so safety is covered. The description adds non-obvious context beyond that: app-derived identifiers are treated as untrusted data and must not be followed as instructions, a prompt-injection guardrail that an agent could not learn from structured fields alone.

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

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

Two tight sentences with zero padding; the purpose is front-loaded and the security caveat follows. The second sentence is somewhat generic boilerplate but earns its place as a safety guardrail.

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 must convey return shape, and 'status and compact metrics' is only a rough sketch of what comes back. Combined with the undocumented scan_id param and no usage guidance, it is adequate but leaves real gaps an agent must guess at.

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 single scan_id parameter has no documented meaning, format, or provenance anywhere. The description only hints at scope via 'Lovable-origin round' but never ties that to scan_id or explains accepted values, leaving a gap it should have filled.

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 ('Returns status and compact metrics') scoped to a 'Lovable-origin round', which distinguishes it from siblings like start_scan and retest_finding. However, 'round' is unexplained jargon that likely maps to the scan_id concept, so an agent must infer the connection rather than being told 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?

There is no statement of when to call this versus siblings such as start_scan or get_app_onboarding_status, nor any prerequisite or post-scan context. Usage is only implied by the tool's name and the mention of a round.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and repeatability profile is covered. The description's 'Queues' adds useful async/queued context beyond the annotations, but it does not disclose permissions, latency, or what a 'fresh round' entails.

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

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

A single sentence with the action verb front-loaded and no wasted filler. It is efficient, though the phrase 'a fresh round for the verified app' is slightly circuitous compared to simply naming the finding retest.

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, 33% parameter coverage, and a queued (asynchronous) mutation, the description should explain what the retest produces, whether the call blocks, and the relationship to the mandatory idempotency_key. None of this is covered, leaving notable gaps for an agent to call it correctly.

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

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

Schema coverage is only 33%, with scan_id and finding_id undocumented in the schema, so the description must compensate but largely does not. 'A previous finding' loosely maps to finding_id and 'verified app' hints at scan context, but scan_id is never referenced and no format or ID-source guidance is given.

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

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

The description pairs a specific action ('Queues a fresh round') with a clear target ('a previous finding can be checked again'), so an agent understands this re-runs verification on an existing finding. It stops short of naming how it differs from siblings like start_scan, so differentiate-ability is only 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?

There is no explicit when-to-use, no prerequisites, and no mention of alternatives such as start_scan or get_fix_prompt. The clause about checking a previous finding again hints at the trigger context (after a fix) but leaves routing entirely 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 openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context that this queues an asynchronous 'basic' round on an already-verified app, but it omits what happens while the round runs, how to poll it, or any runtime/cost constraints.

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

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

A single sentence with the scoping precondition front-loaded and no wasted words. Its brevity edges toward under-specification (e.g. what 'basic' means, what 'Guarita' refers to) rather than pure crispness.

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 and an async queueing tool, an agent still lacks the essentials for follow-through: whether the call returns immediately, how to observe progress, and how the result relates to get_scan_summary. Annotations cover the safety profile, but the operational picture is incomplete.

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

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

Schema description coverage is 50%: idempotency_key is documented in the schema, but onboarding_id carries no description anywhere. The description adds no parameter meaning beyond loosely implying that onboarding_id identifies the verified app, so the gap is not compensated.

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 ('Queues') and resource ('a basic security round'), and scopes it to an app already verified through Lovable. The precondition implicitly separates it from its onboarding siblings (begin_app_onboarding, complete_app_onboarding), though it never names an alternative directly.

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 'for an app already verified through Lovable' gives a real prerequisite, which is more than most definitions offer. However, it says nothing about when NOT to use it, what to do if the app is not yet verified, or how this relates to retest_finding or get_scan_summary.

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