Login Vault

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

With no annotations present, the description carries the full disclosure burden and does a fair job: it declares the authorization requirement ('Owner only') and a data-safety guarantee ('Never contains secrets'), which an agent cannot infer from the schema. It does not state read-only semantics explicitly or describe pagination/ordering behavior of the returned history.

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

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

Two compact sentences with the access constraint front-loaded and no filler. Every clause (ownership, fields returned, no-secrets guarantee) 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 simple, single optional-parameter read tool with no output schema, the description covers authorization, the shape of the returned records, and a data-safety caveat. Only pagination/ordering nuance is absent, which is a minor gap.

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

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

Schema description coverage is 100% ('1-200, default 50'), so the single limit parameter is already fully documented in the schema. The description adds no further syntax or defaulting detail, making the baseline 3 appropriate when the schema does the heavy lifting.

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 concrete verb-resource relationship ('the last uses of your vault') and enumerates the fields returned (who/bot label, login, domain, what happened), so an agent knows this is the activity/history listing. It is distinguishable from session-oriented siblings like open_session or session_fetch, but it does not explicitly contrast itself with the closest sibling, weekly_report.

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?

'Owner only' communicates a permission precondition, which is useful, but there is no guidance on when to call this versus weekly_report or other reporting tools, and no exclusions or prerequisites beyond the ownership note. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the authorization requirement (owner only), the credential scope limitation (only the logins you name), irreversible one-time disclosure ('Shown once; we store only its hash'), and reversibility (revocable). These are exactly the traits an agent must know before generating a secret.

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 short clauses, zero waste, and the most safety-critical fact ('Owner only') is front-loaded. Each sentence adds a distinct fact the 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 small two-param mutation with no annotations and no output schema, the description covers everything material: permission gate, what the returned secret is and that it is shown once, its scope, and how to revoke it. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description restates the gist ('the logins you name') and implies the label identifies the bot, but adds no format, naming, or validation detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Make a per-bot key (vk_...)') plus the key's defining constraint: it can only open sessions on named logins. This distinguishes it cleanly from siblings like save_login, open_session, and revoke_bot_key.

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 an explicit prerequisite ('Owner only') and routes the agent to the sibling that undoes it ('Revoke any time with revoke_bot_key'), which is real when-to-use guidance. It stops short of contrasting itself with alternatives for other key/credential flows, so not a 5.

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

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

With no annotations, the description carries the full burden, and it delivers the two most important facts: an authorization requirement ('Owner only') and the destructive blast radius (kills open sessions, removes the login from every bot key). It stops short of stating irreversibility, confirmation behavior, or what happens if the named login does not exist.

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

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

Two compact sentences with the permission constraint front-loaded and no redundant restatement of the tool name. Every clause adds a distinct fact (auth level, target, cascade effects).

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

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

For a one-parameter delete tool with no annotations and no output schema, the description covers the critical risk information an agent needs (auth requirement plus cascade scope). It is close to complete, lacking only failure-mode and irreversibility detail.

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 'name' parameter, and the description never clarifies whether it is the login label, an ID, or something else. The only hint is that a 'saved login' is being deleted, which barely compensates for the documentation 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 ('Delete a saved login') and immediately scopes what deletion entails ('end its open sessions and remove it from every bot key'). This clearly separates it from save_login, list_logins, and end_session without needing the schemas.

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

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

The 'Owner only' prefix gives a real permission precondition, which is useful context. However, it never says when to prefer this over alternatives like end_session or revoke_bot_key when only partial cleanup is wanted, leaving usage 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?

No annotations are supplied, so the description carries the full burden. It does disclose one concrete side effect ('wipe its cookies'), which is real behavioral information beyond the schema, but it says nothing about reversibility, whether the session is invalidated server-side, or authorization requirements for a destructive 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?

One short front-loaded sentence with zero filler. It is efficient, though terse to the point of leaving obvious gaps unaddressed.

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?

A destructive, annotation-less tool with an undocumented required parameter and no output schema needs more than seven words. Missing: what 'session' is, whether the end is immediate and irreversible, and any effect on concurrent callers.

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 'session' parameter, and it does not. It never says whether 'session' is an ID, token, or name, nor what format is expected.

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 ('End') and resource ('a session'), and the cookie-wipe clause clarifies the effect. It is distinguishable from siblings like open_session or session_fetch by implication, but it never explicitly contrasts itself with them.

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

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

The word 'now' hints at immediacy but gives no condition for choosing this tool over open_session, session_fetch, or delete_login. No prerequisites, no when-not-to-use guidance.

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

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

With no annotations the description carries the full burden, and it delivers meaningful behavioral context: the returned fields, the explicit 'never secrets' guarantee, and the owner-key vs bot-key visibility model. It omits pagination, ordering, and result-size limits, so it is strong but not complete.

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 the core purpose and returned fields front-loaded ahead of the secondary authorization detail. 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 and no annotations, the description does the necessary work of naming return fields, the secrets exclusion, and the permission model. Missing pagination/ordering behavior is a minor gap for a simple zero-parameter 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?

The tool takes zero parameters, so the schema imposes no semantics to explain and there is nothing for the description to compensate for.

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

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

States a specific verb ('List') plus resource ('saved logins') and enumerates what is returned, cleanly distinguishing it from siblings like save_login and delete_login. An agent can identify it without opening a schema.

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

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

The description explains the authorization context (owner key expands results, bot key is scoped down), which implies usage conditions, but it never explicitly states when to pick this over alternatives such as audit_log or session_fetch, and gives no when-not guidance.

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

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

With no annotations the description carries the full burden, and it delivers: credential substitution, https-only posting inside allowed hosts, encrypted cookie storage, an opaque session id return, scope/daily-cap enforcement, audit logging, CAPTCHA/new-device handling, and free-tier dry-run behavior. This is rich behavioral disclosure an agent cannot get from the schema.

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

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

Dense but front-loaded: the core action and its non-exposure guarantee come first, then mechanics, then limits and edge cases. Every clause carries information, though the single long sentence crams several concerns together and could be split for easier scanning.

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 6-parameter mutation-style tool with nested objects, no annotations, and no output schema, the description covers the return value (opaque session id), the safety profile (scope/cap checks, audit log), and the failure path (CAPTCHA → request_human). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning the schema lacks: url must be https and inside the login's allowed hosts, and the {{username}}/{{password}}/{{totp}} placeholders are resolved server-side from the saved login. That extra constraint context justifies going above baseline.

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

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

States a specific verb and resource ('Sign in with a saved login') and immediately distinguishes itself from save_login/list_logins/end_session by making clear it performs the actual authentication using stored credentials without exposing them. The scope ('without seeing it', placeholders filled server-side) is uniquely identifiable.

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

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

Gives concrete conditions: it is checked against the login's scope and daily cap, and on CAPTCHA/new-device it suggests next_step request_human (Human Handoff relay). It also flags the free-tier behavior ('watch-only logs would_use_vault and signs in nowhere'). It stops short of explicitly naming sibling alternatives, but the context is clear enough to select it correctly.

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

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

With no annotations, the description carries the full load and does well: it discloses the required role (owner), the immediacy/irreversibility of the action ('right away'), and the cascading destruction ('end every session it opened'). It does not state whether revocation is permanent or what the call returns, keeping it short of a 5.

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, zero filler, with the permission gate and destructive scope front-loaded before the action detail. Every clause conveys distinct information.

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

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

For a single-parameter mutation tool with no annotations and no output schema, the description covers the essentials: authorization, effect, and cascade. It stops short only on irreversibility/reversibility and error behavior, which are minor for this scope.

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 parameter bot_id has 0% schema description coverage, so the description must compensate — it does not. It refers to 'a bot key' while the parameter is named bot_id, leaving the identifier format (key ID vs bot ID) and whether a key handle is needed genuinely ambiguous.

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 ('Revoke a bot key') and immediately names the side effect ('end every session it opened'), which separates it from the inverse sibling create_bot_key and from the narrower end_session. An agent can identify the operation without opening the schema.

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

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

The 'Owner only' gate is a genuine usage precondition, so context is present. However, it never contrasts with end_session, which also terminates sessions, nor explains when revoking a key is preferable to ending individual sessions — the key ambiguity among these siblings 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?

With no annotations, the description carries the full burden and does well: it discloses encryption at rest, that password and TOTP secret are never returned by any tool, and the free-tier behavior ('stores nothing and logs would_use_vault'). It does not say what happens when a login with the same name already exists (overwrite vs. error) or what save_login itself 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?

Four dense sentences, front-loaded with the owner-only precondition, and every sentence carries information (auth, encryption, environment, tier behavior). Slightly packed 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?

For a mutation tool with no annotations and no output schema, the description covers permissions, environment, security guarantees, and free-tier divergence. The remaining gap is idempotency/duplicate-name behavior, which an agent needs before re-saving the same login.

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%, so the schema already documents most fields. The description enumerates the scope contents (allowed hosts, allowed methods, daily cap, session TTL), but this largely restates the nested schema descriptions rather than adding format, bounds, or interaction semantics.

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

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

States a specific verb and resource ('Store one login') plus the mechanism (sealed with AES-256-GCM). It is clearly distinguishable from siblings like list_logins, delete_login, and open_session, which operate on already-stored or session-level resources.

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 constrains the caller ('Owner only... never a bot key') and the execution environment ('Run it from your own machine, not inside the bot'), which is real when/when-not guidance. It stops short of naming alternative tools for related tasks, so it does not reach 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?

With no annotations, the description carries the full burden and does useful work: it discloses that passwords, TOTP secrets and codes are redacted from the reply and that cookies never leave the vault, plus the host/method enforcement. It omits error/rate-limit behavior and what a failed or blocked request looks like, keeping it from a 5.

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

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

Three dense sentences, zero filler, front-loaded with the action and followed by constraints and security behavior. Every clause carries information an agent needs before calling.

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 no-annotation, no-output-schema tool the description covers the essential prerequisites, input constraints and the security-relevant behavior of the reply. It leaves minor gaps around what the response actually contains (status/body shape) and failure modes.

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 20% (just body's terse note). The description does add meaning for url (https, allowed hosts), method (allowed methods) and session (must be open), which is genuine compensation. But body and headers are undocumented in both schema and description, leaving two of five parameters opaque.

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?

Clear specific verb and resource: 'Make one request inside an open session.' An agent immediately understands this sends a single HTTP request through an authenticated session, distinguishing it from open_session/end_session siblings. It does not name a sibling directly, 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?

States a clear precondition ('inside an open session') and two hard constraints on inputs (https URL within the login's allowed hosts, method within allowed methods). It stops short of explicitly naming open_session as the prerequisite tool or describing when to prefer it over other ways of hitting a host.

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?

No annotations, so the description carries the burden. It adds useful context: free tier of 500 calls/day, not metered. However, it doesn't state whether the call itself counts toward quota, rate limits, or whether the upgrade link is static/dynamic.

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, front-loaded sentences with no waste. The primary output is stated first, followed by the supporting quota context.

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 no-param, no-output-schema read tool, the description covers what is returned (usage and upgrade link) and the quota context. It lacks detail on return format, but that's minor given the simplicity.

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?

Zero parameters, so baseline is 4. The description correctly indicates the scope is implicit (your key or IP), needing no input.

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 ('Show') and resource ('today's usage for your key or IP') plus a secondary output (the upgrade link). It's clearly distinguishable from siblings like budget_status and weekly_report which deal with budgets/reports.

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

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

Implied usage via 'today's usage' and the free-tier context, but no explicit when-to-use or when-not-to-use versus siblings like budget_status or weekly_report. The agent must infer that this is a quick self-check rather than a budget query.

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

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

With no annotations, the description carries the full burden. It does disclose two behavioral facts an agent needs: the operation is read-only, and it requires an API key. However, it says nothing about rate limits, whether the window is fixed at 7 days or configurable, 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?

One dense sentence front-loads the purpose and content list before the trailing caveats. It is compact and wastes little, though the trailing fragments 'Read-only. Needs a key.' are slightly clipped rather than integrated.

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 report with no output schema, the description enumerates what the report contains, which is enough for an agent to decide whether to call it. Auth and safety are covered; only output format and window flexibility are left unstated.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The schema description coverage is trivially 100% given the empty properties object.

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 deliverable (a weekly summary report) and enumerates its content — sign-in domains, sessions opened, blocked attempts, per bot — which implicitly separates it from raw-event siblings like audit_log and session_fetch. It does not explicitly name an alternative, 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?

There is no guidance on when to call this versus audit_log (raw events) or session_fetch (session detail). The only usage-adjacent statement is the precondition 'Needs a key', which is an auth note rather than selection advice.

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