secureflows-mcp

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

No annotations are present, so the description carries full burden, and it does so richly: explains 302 redirect with sessionToken/state, 400 on non-allowlisted redirect URI, no redirect on errors, create-vs-renew logic, payload ignored on renew, ttl_seconds default/range, and best-effort email backfill. This goes far beyond a simple action statement.

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?

Structured with numbered steps and bolded terms, and the essential endpoint context is front-loaded. Minor redundancy ('No Authorization header' appears twice) and the length is long, but each paragraph earns its place given the tool's complexity.

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 with no output schema and no annotations, the description is exceptionally complete: it covers required parameters, optionals, constraints, error responses, redirection behavior, and configuration guidance. An agent has everything needed to select and 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?

Even though schema coverage is 0%, the description explains all key parameters and their interplay: payload only on create and must not combine with session_token, ttl_seconds range and default, session_token renewal semantics, client_redirect_uri allowlisting, and response query params. This is substantial added meaning beyond the raw schema.

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

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

States a specific verb and resource: 'Browser redirect endpoint used after hosted /app/sessions/login.' It clearly delineates the tool's role in the auth flow (callback after login), and the emphasis on no Authorization header distinguishes it from direct API session tools. The create-vs-renew explanation further clarifies its scope.

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

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

Provides clear context: explicitly says it is for the browser redirect after hosted login, that no Authorization header is used, and recommends using connection.workspaceName/appId as stable config. It does not explicitly name when-not-to-use alternatives, but the context is unmistakable.

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 provided, so the description carries the full behavioral disclosure burden. It clearly discloses the destructive side effect (removes a key), the conditional return behavior ('returns true if the key existed'), and the auth transport mechanism. It does not discuss error responses or behavior when the key is absent, but the core behavioral traits are transparent.

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 four concise sentences, each earning its place: behavior/return value, source endpoint, auth requirement, and config preference. The most important information is front-loaded in the first sentence. There is no filler or unnecessary elaboration.

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

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

Given there is no annotations and no output schema, the description covers the key elements needed to invoke the tool: the operation, the target key, the required auth token, and the endpoint. It does not cover edge cases like errors or the exact response when the key does not exist, but the 'returns true if the key existed' phrasing implies the behavior clearly enough for most agent scenarios.

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 low, so the description must compensate for parameter meaning. It adds useful semantics by identifying `key` as the URL path parameter and describing auth.sessionToken as a Bearer token. It also references connection.workspaceName and connection.appId as preferred config. However, it does not describe all parameters such as connection.host, and the return-value relationship to parameters is only partially explained.

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

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

The description clearly states the action with a specific verb and resource: 'Removes `key` from the session payload and returns `true` if the key existed.' This is unambiguous and distinguishes it from sibling tools like post_sessions_set_key, which perform the opposite operation. The endpoint source further reinforces what the tool does.

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 provides practical usage context by stating the auth requirement ('Requires auth.sessionToken and forwards it as a Bearer token') and advising stable config via connection.workspaceName and connection.appId. However, it does not explicitly state when to prefer this tool over siblings or when not to use it, so guidance is implied rather than fully explicit.

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

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

With no annotations, the description fully carries the behavioral burden. It discloses side effects (token revision increment, Firebase refresh token revocation, Clear-Site-Data setting), idempotent best-effort behavior, and the fact that expired sessions still complete logout without returning 401.

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 detailed but well-structured with clear section headers and bullets. Every sentence adds value, from the critical client rules to the behavioral guarantees, and the most important usage constraint is front-loaded.

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

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

The description covers prerequisites, required parameters, security-relevant client behavior, error edge cases, and redirect behavior. Since there is no output schema, the explanation that the endpoint redirects to redirect_uri is sufficient. No critical calling information appears to be 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?

Despite low schema coverage, the description adds meaningful semantics for the key parameters: session_token is the JWT to invalidate and redirect_uri is the post-logout destination. It also warns against putting session_token inside redirect_uri and gives guidance about using connection.workspaceName and connection.appId as stable config.

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

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

The description clearly identifies this as a browser-friendly logout endpoint for cross-site clients, using a specific verb (logout) and resource (auth session). It distinguishes itself from likely alternatives by emphasizing top-level navigation and Clear-Site-Data behavior.

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 gives strong usage context: use as top-level navigation, not XHR/fetch, and in first-party context to ensure cookie clearing. It does not explicitly name alternative tools such as post_auth_logout, so it lacks a direct when-not-to-use reference, but the practical guidance is clear.

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 behavioral burden, and it does well by explaining the embedding mechanism, the vector index, the public nature of the docs, and that no auth header is needed. The GET source also implies read-only behavior, though output format and failure cases are not detailed.

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 compact, front-loaded with the essential search behavior, and every sentence contributes useful information. It includes endpoint, auth, and configuration guidance without redundancy.

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

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

The description explains what the tool does and important auth/configuration context, but with no output schema it does not describe the result shape or fields. It also does not mention default limit behavior beyond the schema's max cap, so an agent may still be uncertain about the exact response.

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 description adds useful semantics for connection.workspaceName and connection.appId by recommending them as stable configuration. The q and limit parameters are primarily covered by the input schema, and the description does not add much about how limit or q should be formed beyond the schema text.

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

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

The description clearly states that the tool embeds a query with Ollama and returns the closest public doc chunks from a pgvector-backed search index. The resource and behavior are specific, and it is readily distinguishable from the unrelated auth/session 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?

The description gives clear usage context: it is for semantic documentation search, works over a documented GET endpoint, and requires no Authorization header. It does not explicitly name alternatives or exclusions, but no sibling tool provides comparable doc-search functionality, so the omission is minor.

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 behavioral disclosure burden. It does well by disclosing the response shape, the empty-payload case, the auth requirement, the Bearer token forwarding, and the fact that the payload is decrypted. It does not mention error behavior or rate limits, but for a simple GET-like read operation the provided detail is strong.

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 compact and front-loaded with the core purpose, then adds response shape, auth requirements, and configuration guidance. Each sentence contributes useful information without repetition or filler. It is appropriately sized for the tool's complexity.

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 with no annotations and no output schema, the description covers the essential invocation details: purpose, auth requirement, source endpoint, response shape, and config preferences. It could be more complete by explicitly mentioning the required connection.host and clarifying that the operation is read-only, but overall it gives an agent enough to invoke 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 description coverage is reported as 0%, so the description must compensate. It explicitly explains auth.sessionToken and gives purpose to connection.workspaceName and connection.appId, but it does not clarify connection.host or the empty body/query/params containers. The description adds meaning beyond the schema for some parameters but not all.

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

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

The description clearly states the verb and resource: it returns the decrypted session payload for the current authenticated session token. It also includes the source endpoint, which helps identify the operation. However, it does not explicitly differentiate itself from sibling tools like get_sessions_my or get_sessions_identity, so the distinction is somewhat 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?

The description provides useful context: it requires auth.sessionToken and explains how it is forwarded as a Bearer token. It also advises preferring connection.workspaceName and connection.appId as stable config. However, it does not state when to choose this tool over sibling session-related tools, nor does it give exclusions or alternatives.

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

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

With no annotations, the description carries the full burden of disclosing behavior. It states the response is the decrypted payload value, clarifies the meaning of 404, and indicates the authentication mechanism (Bearer token). It does not mention potential rate limits, other error codes, or whether the operation has side effects, but as a simple GET, these are less critical.

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 succinct and well-structured: a clear one-sentence purpose, an important error-handling note, and then concise technical details (HTTP method, authentication, config preference). Every sentence adds value without redundancy.

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

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

Given there is no output schema, the description sufficiently explains what the tool returns (the decrypted value) and covers a key error case (404). It does not specify the exact response format (e.g., JSON structure, content type), but for a simple value retrieval this may be acceptable. The description is complete enough for an agent to understand the tool's core usage.

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 input schema already provides descriptions for all parameters (key, host, appId, workspaceName, sessionToken), so the baseline is high. The description adds extra context for sessionToken by specifying it is forwarded as a Bearer token, and for workspaceName/appId by recommending them as stable config. It does not add meaning for key or host, but the schema descriptions are already clear.

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 ('Retrieves') and clearly identifies the resource (a single value from the session payload for a given key). It distinguishes itself from sibling tools like get_sessions (list) and get_sessions_identity (identity data) by focusing on a single key/value 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?

The description provides practical usage guidance: it explicitly explains the 404 handling as a normal first-use case, mentions the requirement for auth.sessionToken to be forwarded as a Bearer token, and advises preferring connection.workspaceName and appId over dynamically generated identity fields. However, it does not explicitly compare to alternative tools (e.g., when to use this over get_sessions) or mention any preconditions beyond the token.

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 behavioral burden and meets it: it states return values, explicitly lists what is not returned, discloses that `email` is best-effort and may be `null`, and reveals the auth mechanism. This goes well beyond a simple one-line tool description.

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

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

The description is front-loaded with the core return and is well organized, but it is long and includes the somewhat tangential closing sentence about preferring `connection.workspaceName` and `connection.appId` as stable config. Several sentences are valuable, but not every sentence fully earns its place for a simple identity lookup.

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 identity lookup with no output schema or annotations, the description is complete: return semantics, null behavior, auth requirement, source endpoint, SDK path, and exclusions are all covered. An agent has enough context to invoke it correctly for the described correlation use case.

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?

Despite the reported low schema coverage, the description meaningfully documents the key parameters: `auth.sessionToken` is required and sent as Bearer, and `connection.workspaceName`/`appId` are referenced for stable config. It leaves body/query/params implied (they are empty in the schema) and doesn't explicitly map every field, so a small gap remains.

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?

Description opens with the concrete action — returning the authenticated user's `userId` and `email` — and names the exact resource (`GET /api/v1/sessions/identity`). It also differentiates from the many session siblings by explicitly saying it does not return Firebase UID or session payload, so an agent won't confuse it with session listing/renewal 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 clear when-to-use: use `userId` as the stable correlation key when a backend must link an external event back to a user. It also gives a when-not-to: do not use session token or session id because they expire and rotate, and it requires `auth.sessionToken` which it sends as a Bearer token.

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 provided, the description carries the full behavioral burden. It discloses the auth requirement (auth.userToken forwarded as a Bearer token), the enableSelfService prerequisite, the fact that payloads are only included for active sessions, and pageSize clamping. This is strong, though it omits error behavior and response shape 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?

The description is compact and front-loaded: purpose first, then the self-service requirement, key behavioral quirk, and pagination/sort notes. Nearly every sentence earns its place, though the explicit 'Source:' line and trailing config-preference sentence are somewhat tangential.

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 five-parameter self-service list endpoint with no output schema, the description covers the critical prerequisite, auth flow, payload filtering behavior, and pageSize limit. It is enough for an agent to select and call the tool correctly, though an explicit note about the response shape or how to page through results would make it fully 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?

The input schema already documents q, app_id, status, pageSize, auth, and connection parameters, so the description does not need to repeat them. The description adds useful context by tying sort keys to the admin session list and recommending stable connection config. However, it leaves page and dir semantics to the schema and does not compensate for all undocumented parameters.

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

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

The description opens with 'Returns a page of sessions for the current user within the current workspace,' which is a specific verb+resource statement that clearly identifies this as the self-service 'my sessions' endpoint. It also names the canonical HTTP source. It does not explicitly contrast itself with the sibling admin-level get_sessions tool, so it is not a 5.

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

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

The description gives clear context: it is a self-service dashboard endpoint, it requires workspace enableSelfService: true, and it advises preferring connection.workspaceName and connection.appId as stable config. It does not explicitly say when to avoid this tool or name get_sessions as the admin alternative, so it stops short of full 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?

The description fully discloses the effects: it invalidates the session token, revokes Firebase refresh tokens, sets Clear-Site-Data, and explicitly states what it does NOT do (does not delete or modify the session payload/row except tokenRevision). This is highly transparent given there are no annotations.

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 well-organized with sections and bullet points, but it is somewhat verbose, with some redundancy (e.g., repeating the 'without revoking' idea later clarified). The key information is front-loaded, so it remains effective.

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

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

The description covers the essential behavior, side effects, and a critical warning. It does not describe the response format or error cases, but since no output schema is provided and this is a logout operation, the omission is acceptable. Overall, it is complete for most usage scenarios.

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 input schema already provides descriptions for all parameters, and the tool description adds minimal extra meaning, such as noting that the sessionToken is forwarded as a Bearer token. This is helpful but not a major addition beyond the schema's existing coverage.

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

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

The description clearly states the tool logs out the current session, but the phrase 'without revoking it' is contradictory to the subsequent behavior of invalidating the session token and revoking refresh tokens. This ambiguity might confuse an agent, though the overall intent is discernible from the rest of the text.

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

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

The description explicitly warns against using this tool in browser contexts and recommends the alternative GET /api/v1/auth/logout redirect helper for browser apps. It also explains the behavior in detail, making it clear when to use this endpoint versus the sibling tools.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses the auth verification step, the session creation side effect, payload serialization/defaulting, the JWT response with subject=internal session id, a 1-hour TTL implementation detail, and best-effort email persistence. This is substantial and transparent, though it stops short of describing error behavior or idempotency.

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 well-organized: core behavior first, then side effects and alternative routing, then source and configuration guidance. It is dense but each sentence contributes useful information. Slight redundancy exists between 'Requires auth.firebaseToken' and the earlier 'Verifies Firebase ID token', but overall it is structured effectively.

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

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

Given the tool has no output schema, the description explains the key return value (sessionToken JWT) and includes source endpoint, auth requirements, TTL, side-effect email persistence, and a routing alternative. It lacks error scenarios and response envelope details, but it is sufficient for an agent to select and invoke the tool correctly.

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

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

The schema has 0% coverage per the context signal, so the description must compensate. It adds meaning for payload (serialized, defaults to {}), auth.firebaseToken (verified and sent as Bearer), and connection.workspaceName/appId (preferred stable config). However, it does not add detail about body.app_id beyond what the schema itself already says, and it omits guidance for host, so compensation is partial.

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

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

The description clearly states it verifies a Firebase ID token, creates a session for workspaceName, stores payload, and returns a sessionToken JWT. It also distinguishes itself from post_sessions_get_or_create by explicitly mentioning that the alternative should be preferred for hosted-login-style flows, making sibling differentiation strong.

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 gives explicit routing guidance: 'Prefer POST /sessions/get-or-create for hosted-login-style flows that should reuse an active session.' It also provides operational prerequisites such as requiring auth.firebaseToken and forwarding it as a Bearer token. It does not cover exclusions for all sibling tools, but it gives clear context for the most relevant alternative.

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 fully carries the behavioral burden, and it delivers: it explains Firebase token verification and Bearer forwarding, reuse criteria, JWT return behavior, activity touch, payload-ignored-on-reuse semantics, default 1-hour TTL, and best-effort email backfill. No behavioral surprises are hidden.

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 longer than average but every sentence adds a distinct piece of behavior: token verification, reuse semantics, payload handling, TTL, email backfill, endpoint, and configuration preference. Slight redundancy exists between the opening token verification and the later auth.firebaseToken requirement, but the structure is nonetheless efficient and front-loaded.

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

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

For a tool with no annotations and no output schema, the description is remarkably complete: it covers the auth mechanism, request shaping, reuse vs. creation behavior, payload side effects, returned token, TTL, email persistence, and config best practices. An agent has enough context to invoke the tool correctly and predict its side effects.

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

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

Although schema description coverage is 0%, the description adds essential meaning beyond the schema: auth.firebaseToken becomes a Bearer token, body.payload is only applied on new rows, body.app_id is tied to per-app policy and fresh-payload behavior, and connection.workspaceName/appId are recommended stable defaults. This compensates well for the schema-only gaps.

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

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

The description names a specific operation with a clear conditional: verify Firebase token, reuse the most recently created active session for the given key, or fall back to creating a new session like POST /sessions. This distinguishes it from plain session creation and renewal tools in the sibling list.

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

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

It gives concrete guidance on when the tool is appropriate and when it is not: payload is ignored on reuse, so to get a fresh payload one should use a dedicated app_id or revoke old sessions. It also recommends stable connection.workspaceName and connection.appId config over dynamic identity fields, though it does not exhaustively compare against every sibling.

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 provided, the description carries the full burden of behavioral disclosure. It does this exceptionally well by revealing that JWT expiry is not enforced, tokenRevision is incremented, previous session JWTs become invalid, server-side expiry is extended by 1 hour, and email backfill is best-effort. These are exactly the non-obvious side effects an agent needs to know.

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

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

The description is dense but front-loaded with the core behavior, then covers side effects, return value, and invocation details. Almost every sentence adds necessary information, though the final note about preferring stable connection config is slightly tangential and could be integrated more cleanly.

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 complex tool with no annotations and no output schema, this description is highly complete. It covers authentication, token parsing and validation rules, side effects, return values, expiry extension, URL encoding, and required auth fields. An agent has enough context to invoke this tool correctly and anticipate its effects.

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?

Despite the schema coverage signal showing 0%, the description meaningfully explains the critical parameters: sessionToken is a potentially expired internal JWT in the path and must be URL-encoded, auth.firebaseToken is required and sent as a Bearer token. It also adds practical guidance about connection.workspaceName and connection.appId, going well beyond the bare schema.

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

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

The description clearly states a specific action: renew a session JWT by verifying a Firebase token, invalidating prior session tokens, and returning a new token. It explicitly differentiates what this tool does from sibling tools like post_sessions_revoke and post_sessions_revoke_session_id by focusing on token renewal rather than revocation.

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 exact use case: replacing an expired session token while still validating the Firebase identity and session ownership. It also specifies the URL form and URL-encoding requirement, but it does not explicitly mention alternatives or when not to use this tool, so it stops short of full exclusion 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 behavioral burden. It discloses that the tool performs a destructive session revocation and explains that auth.sessionToken is forwarded as a Bearer token, which is material to invoking the tool correctly. It stops short of describing response or error behavior.

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 plus an endpoint source line carry the needed information with no fluff. The action is front-loaded, followed by use case, then technical details.

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 relatively simple revoke-by-token operation with empty body/query/params, the description covers the core inputs, endpoint, and use case. It does not describe the response or failure modes, but the tool's purpose and required authentication are sufficiently complete for 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 coverage is reported as 0%, so the description must compensate. It does by explaining how auth.sessionToken is used and by advising stable connection fields (workspaceName/appId) over dynamically generated identity fields. The phrase 'Requires auth.sessionToken' adds semantic requiredness even though the JSON schema lists it as optional.

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

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

The first sentence names a specific action ('Revokes') and a specific resource ('the session referenced by the internal SESSION Bearer token'), clearly distinguishing this from sibling tools like post_sessions_revoke_session_id. The title reinforces the by-token selection criteria.

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 identifies the target use case: automation clients that hold only a session token and want to revoke it cleanly. It does not explicitly contrast with alternatives or say when not to use it, but the context is clear enough for an agent to route 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 behavioral burden. It discloses that auth.userToken is required and forwarded as a Bearer token, and that the workspace must have enableSelfService enabled. It does not detail side effects or error behavior, but the revoke action is clear from the description and title.

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 compact and front-loaded: purpose, prerequisite, source, auth requirement, and config guidance are each on their own line. The source line is mildly redundant with the tool name, but the overall structure is easy to parse and free of 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?

Given no annotations and no output schema, the description covers the essential invocation context: the call's scope, the workspace feature flag, the auth token requirement, and a config preference. It does not describe the response shape or failure modes, but for a single-session revoke action the key operational details are present.

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. It does add meaning by explaining auth.userToken's forwarding behavior and the intended stable-config role of connection.workspaceName and connection.appId. However, it leaves params.sessionId semantics implicit, relying on the path template and tool name rather than describing the parameter directly.

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: 'Revokes a session owned by the caller in the current workspace.' The phrase 'Self-service dashboard endpoint' helps distinguish this from the more generic sibling post_sessions_revoke, and 'owned by the caller' scopes it to the current user.

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 gives clear usage context: it is a self-service endpoint, restricted to the caller's session, and requires workspace enableSelfService: true. It does not explicitly name an alternative tool to use when those conditions are not met, so it stops short of a 5.

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

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

Discloses that it sets a key and returns the updated payload, and explains the unwrapping behavior for the body. However, it does not mention side effects, idempotency, or error conditions.

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?

Description is about three sentences, covering key aspects without excessive verbosity. It includes source and a preference note, but remains focused.

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 main usage, but lacks details on response structure (though it says returns updated payload), error handling, and edge cases. The schema is complex, but the description gives enough to call the tool, though not exhaustive.

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?

Adds meaning to the body parameter by explaining the unwrapping of `{ value: x }`, and clarifies that auth.sessionToken is forwarded as Bearer token. The schema already describes key and host, but the description enriches 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?

States a specific verb 'Set' and resource 'key in the encrypted session payload', and describes the return value. Clearly distinguishes from sibling tools by its focus on setting a 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?

Does not explicitly mention when to use this tool over alternatives like get or delete. Provides some guidance on body format and connection config, but lacks direct comparisons.

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 itself discloses the key behavioral facts: it requires no token, is safe during scaffolding, always targets /app/sessions/login, and never emits the legacy /app/login URL that causes an infinite redirect loop. It also warns against hand-built URLs as a root-cause source of login-loop and stale-renewal bugs, giving the agent real pre-call behavioral knowledge.

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?

Five sentences, front-loaded with the core purpose and followed only by high-value context (when safe, which route, why not hand-build). No filler or redundant restatement of schema details.

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

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

Given no annotations or output schema, the description plus rich input schema covers invocation phase, safety, target path, and failure modes. The return type is apparent from 'Builds ... URL', and the schema covers all parameters, so nothing an agent needs to select and 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% with detailed descriptions, defaults, and enum semantics, so the baseline is 3. The description adds contextual warnings rather than parameter-level detail, which is acceptable because the schema already 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?

States a specific action ('Builds') and precise resource ('hosted-login redirect URL'). It further disambiguates the intended target (/app/sessions/login) from the legacy console URL, so an agent can distinguish this from related login-URL construction 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?

Explicitly says when to call it ('at app-scaffolding time, before any user session exists'), that it needs no token, and directs the agent to use it instead of hand-building with URLSearchParams. It also names the legacy /app/login path as something to avoid, which is a clear exclusion.

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 discloses that the tool refuses to build URLs matching anti-patterns, always instructs top-level navigation, and explains the consequence of fetch (browsers silently ignore Clear-Site-Data, causing cookie survival). It also clearly states it never builds a revoke request and why. This is exceptionally transparent.

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 well-structured, front-loaded with the core purpose, then systematically addresses anti-patterns, navigation behavior, and revoke differentiation. Every sentence carries meaningful information without redundancy, and the length is justified by the safety-critical nature of the tool.

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

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

Given the complexity and absence of an output schema, the description effectively explains what the tool produces (a URL that instructs top-level navigation) and its safety constraints. It does not explicitly state what happens when it refuses a request (error vs. return null/log), but the description is otherwise comprehensive 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 100% and all parameters already have descriptive annotations, including the constraints on postLogoutRedirectUri (not /callback, not contain session_token). The description adds rationale behind these constraints but does not introduce new parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

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 ('Builds'), a specific resource ('redirect-logout URL'), and immediately differentiates from siblings by emphasizing it refuses to build URLs with anti-patterns and never builds a revoke request. The mention of top-level navigation versus fetch clearly sets this apart from other logout-related tools.

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

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

It explicitly states when to use this tool (for ordinary sign-out via redirect) and when not to (never for revoke, which is reserved for account deletion). It also advises against using fetch/XHR for the result, reinforcing the correct consumption pattern. This is explicit when/when-not guidance with alternatives.

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

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

With no annotations provided, the description carries the full disclosure burden and does so richly. It reveals that this is heuristic text analysis, not a parser or type checker, explains that some checks operate across the whole file set, and discloses potential false confidence from keyword matching. It also explains file-scope vs project-scope findings and gives severity guidance.

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 long but every sentence adds necessary information, and it is well structured: purpose, usage constraints, finding types with concrete examples, and limitations. The use of bullets and short labels keeps dense content scannable, and the most important operational guidance is front-loaded.

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

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

Given no annotations and no output schema, the description compensates by explaining what findings look like, providing examples of both scopes, warning about limitations, and telling the agent how to interpret error vs needs_review results. It is complete enough for an agent to invoke the tool correctly and act on its results.

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

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

The schema already documents the `files` parameter well, and the description adds essential behavioral semantics beyond it: passing every auth/session-related file in one call matters because some checks are evaluated across the whole set. It also clarifies that project-scope findings depend on what was passed in, which directly informs how an agent should construct the parameter.

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

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

The description clearly states a specific action and resource: 'Checks source you already generated against the secureFlows integration rules.' It distinguishes this static lint tool from sibling auth/session and URL-building tools by emphasizing that it scans code rather than performing session operations.

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 gives explicit when-to-use guidance: no secureFlows token needed, safe at scaffolding time, and all auth/session-related files should be passed in one call. It also states clear exclusions: not a substitute for the Agent implementation checklist and not for checks needing a running app.

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