secureflows-mcp-server

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

With no annotations provided, the description carries the full transparency burden, and it does so exceptionally well. It discloses token verification, allowlist enforcement, create-vs-renew semantics, payload storage rules, ttl behavior, email backfill, response status codes, and error response shape, all of which go far beyond what a generic 'callback' title would imply.

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 with bolded terms and numbered flow steps, making complex behavior navigable. It is somewhat long, and 'No Authorization header' appears twice, but every major behavioral rule 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 complex auth callback tool with no output schema, the description covers the full lifecycle: request context, required/optional parameters, conditional behavior, success response (302 with sessionToken and state), and failure response (400 or JSON error, no redirect). It is sufficiently complete for an agent to know when and how to invoke this endpoint.

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 the schema provides descriptions for some parameters, the narrative description adds critical meaning that the schema alone would not convey: firebaseToken is a Firebase ID token, client_redirect_uri must be allowlisted, session_token may be expired but must validate, payload must be a JSON object and is only stored on create, and ttl_seconds has a default of 0 with a 60–604800 range when set. This gives the agent the full semantics needed to construct valid requests.

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 this is a browser redirect endpoint used after hosted `/app/sessions/login`, with a precise flow of verifying Firebase tokens, checking redirect allowlist, and creating or renewing sessions. It is easily distinguished from sibling tools like post_sessions_get_or_create or post_sessions_renew_session_token because it describes the redirect/callback mechanics, including 302 responses and the lack of an Authorization header.

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: it is used after hosted login, requires no Authorization header, and explains when payload may or may not be sent (create vs renew). It provides clear constraints like allowlist behavior and no redirect on failure, but it does not explicitly name alternative tools or say 'use X instead when not in a browser redirect context,' 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?

The description discloses the primary behavior (removing a key, returning true if it existed) and the authentication requirement. With no annotations provided, it carries the full burden of behavioral disclosure boundaries. It does not mention side effects like key absence behavior beyond the boolean return, but the core mutation and return value are transparent enough for a delete action.

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 action. The second sentence about the source endpoint is useful but not strictly necessary; the third sentence provides configuration guidance. No wasted words, but it could be slightly cleaner by dropping the endpoint line or merging it.

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 the primary behavior and return value, and notes the auth requirementptr. However, it lacks detail on side effects (e.g., whether the deletion is permanent), error conditions, idempotency, or the impact on the session. Given the simplicity of the operation and the presence of siblings with similar parameters, this is adequate but not fully comprehensive.

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 provides descriptions for `key`, `auth.sessionToken`, and connection fields, so the description adds minimal extra meaning. It mentions key and auth.token explicitly, but does not elaborate on `workspaceName` or `appId` beyond the schema, and the description does not compensate for the schema's own coverage. A score of 3 is appropriate per the baseline for adequate schema 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 states a specific action ('Removes `key` from the session payload') and clearly distinguishes it from sibling tools (e.g., set, get). It names the resource (session payload) and the exact effect, making the tool's purpose unambiguous.

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

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

The description gives clear context: it requires `auth.sessionToken`, which is forwarded as a Bearer token, and provides configuration guidance (prefer workspaceName and appId). It does not explicitly state when to use this tool over alternatives (e.g., when to delete versus set a key), but the context strongly implies the use case, earning a 4 rather than 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 provided, the description carries the full behavioral burden and does so thoroughly. It discloses idempotency, best-effort behavior, token invalidation via tokenRevision, behavior for already-expired or superseded sessions, Firebase refresh-token revocation, Clear-Site-Data setting, and redirect 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?

The description is well-structured with a lead paragraph, bolded client rules, and bulleted behavior details. It is information-dense and mostly front-loaded, but the final sentence about stable connection config feels somewhat tangential to logout and slightly dilutes the focus.

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 absence of annotations and output schema, the description is remarkably complete: it covers purpose, invocation context, required query parameters, security constraints, error tolerance, side effects, and redirect behavior. An agent has enough context to correctly invoke this endpoint without needing additional structured metadata.

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 compensates by explaining the purpose of session_token and redirect_uri, including the critical pitfall that putting session_token in redirect_uri silently renews the session. It also adds guidance on connection fields by recommending stable workspaceName/appId usage, though it does not explicitly enumerate every schema property.

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 immediately identifies the endpoint as a 'Browser-friendly logout endpoint' and clearly states its purpose: invalidating the session, clearing cookies via Clear-Site-Data, and redirecting to redirect_uri. It also distinguishes itself from sibling logout-related tools by framing it for top-level cross-site navigation rather than API-style calls.

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

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

Usage guidance is explicit and actionable: use top-level navigation instead of XHR/fetch, clear in-app sessionToken before navigating, and never include session_token inside redirect_uri. It also states that no Authorization header is required, giving concrete when/when-not conditions that an agent can follow.

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 transparency burden. It discloses the HTTP endpoint, embedding model, auth behavior, and the read-only nature of the operation. It does not mention errors, rate limits, or response shape, which keeps it short of complete transparency.

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 drills to the core: what it does, where it comes from, auth requirements, and a config-usage hint. The final 'prefer connection...' sentence is the weakest element, but it is not filler or redundant.

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

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

For a read-only semantic search tool with no output schema, this description is reasonably complete from end to end: purpose, endpoint, auth, and retrieval behavior are covered. Additional details such as pagination or server caps are left to the schema, which does document the limit.

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 useful descriptions for query fields such as 'q', 'limit', and the connection object, so the baseline is acceptable. The description adds extra context around embedding semantics and stable configuration, but it still does little to explain wrapper parameters or edge behavior.

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 action: it embeds the query with Ollama and retrieves the closest public doc chunks from a pgvector index. This clearly distinguishes it from the auth/session sibling tools and establishes exactly what resource it operates on.

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 establishes a clear usage context: semantic documentation search over public docs, with no Authorization header required. It does not explicitly name an alternative tool or provide a 'don't use for', but the context is clear enough for selection among unrelated siblings.

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?

There are no annotations, so the description carries the transparency burden. It discloses the source endpoint, Bearer-token forwarding, flat response shape, empty-payload behavior, and config guidance. Failure modes or explicit read-only confirmation are not covered, but the provided details are substantive.

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 every line adds value: purpose, response shape, endpoint source, auth requirement, and configuration guidance. It is front-loaded 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?

With no output schema, the description appropriately explains the return format and empty-payload behavior, plus auth requirements. For a simple read operation, this is fairly complete, though error behavior and explicit side-effect disclosure are absent.

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

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

Schema description coverage is 0%, so the description must compensate. It explains auth.sessionToken's purpose and forwarding behavior and provides usage guidance for connection.appId and connection.workspaceName. However, it does not mention the required connection.host parameter, which is a notable gap.

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

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

The description clearly states it returns the decrypted session payload for the authenticated internal session token, using a specific verb and resource. It does not explicitly differentiate from sibling tools like get_sessions_my or get_sessions_identity, but the 'internal session token' scoping adds clarity.

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

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

The description implies usage when an authenticated session token is available and the payload is needed. It also advises preferring connection.workspaceName and connection.appId, but it does not explicitly state when to use this tool versus sibling alternatives or when not to use it.

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. It discloses the 404 behavior (important for error handling), authentication requirements (sessionToken forwarded as Bearer), and a tip about stable configuration. This is useful behavioral context beyond 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?

The description is compact and front-loaded, with the main action stated first, then important notes and source. Every sentence adds value, and the markdown bold for the key point improves scannability.

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

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

For a simple-read tool with no output schema, the description covers the main usage, error semantics, auth, and a configuration recommendation. It could mention the response format or pagination, but these are less critical for a single-key retrieval.

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 mentions the key parameter ('for `key`'), but does not explain the `params` wrapper or the `connection` object's role beyond authentication. The tip about connection fields adds some value, but it doesn't fully document all required or optional 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 clearly states it retrieves the decrypted payload value for a given key, which is a specific verb+resource combination. It distinguishes from siblings like post_sessions_set_key (write) and get_sessions (list) by focusing on a single key read.

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 clear context on when to use this tool, including the '404 means key never written' guidance and a note to prefer stable config fields. However, it does not explicitly state when not to use it or name alternative tools for similar scenarios.

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 full burden and excels: it discloses that email may be null, that userId is not derived from Firebase, and that the token is forwarded as a Bearer header. It also surfaces dependency on the persisted email claim, giving runtime expectations.

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 packs in a lot: return values, caveats, SDK usage, endpoint, and auth. The information is dense and mostly front-loaded, though the final sentence about connection config feels tangential and slightly confusing in this context. Minor trimming could improve focus.

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's complexity and lack of an output schema or annotations, the description thoroughly covers return semantics, token auth, and correlation guidance. It could mention error behavior (e.g., invalid token) or rate limits, but it's well above the minimum viable for an identity-lookup tool.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain auth.sessionToken's role and touches on connection.* but not the purpose of host, and doesn't explicitly describe how appId/workspaceName are used. It gives enough for connection-level understanding but leaves some parameter meaning implicit.

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 returns the user's userId and email for an authenticated session token. It explicitly distinguishes itself by noting what it does NOT return (Firebase UID, session payload) and frames the stable ID use case for correlation. This differentiates it well from siblings like get_sessions_my or auth_session_callback.

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 guidance: use userId as correlation key for backend event linking, and explicitly advises against using session tokens/ids because they rotate. It also points to connection.workspaceName and connection.appId as stable config, providing an alternative. However, it doesn't name sibling tools directly, so a slight deduction.

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 disclosing safety and behavior. It explicitly states that payload is included only for active-status rows, pageSize is clamped to 1–200 (default 20), and requires auth.userToken forwarded as a Bearer token. It also notes the self-service requirement. These are key behavioral details, though it does not cover all edge cases like errors or response format.

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

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

The description is a single paragraph of five sentences, each contributing necessary information. It starts with the core purpose, then covers prerequisites, output inclusion, sort behavior, pagination, source, and authentication. There is no fluff or redundancy. The structure is front-loaded and efficient.

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 absence of an output schema, the description provides some indication of the returned page and the conditional payload inclusion. It also covers preconditions (self-service), authentication, pagination, and filtering basics. It does not describe the session object structure or error handling, but for a read-only listing endpoint with many siblings, it is reasonably 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 schema has descriptions for several parameters (q, app_id, status, pageSize, connection fields), but context signals indicate 0% coverage, meaning the description must compensate. The description adds semantic context like 'sort keys match the admin workspace session list' and 'pageSize is clamped' and that payload is only for active rows. However, it does not explain parameters like 'dir' or 'page' beyond what the schema provides. It partially compensates but not fully.

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 and resource with clear scope. It distinguishes itself from the admin 'get_sessions' sibling by emphasizing 'current user' and 'self-service dashboard endpoint.' The mention of 'sort keys match the admin workspace session list' further clarifies its relationship to the admin tool.

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 states a prerequisite (workspace outsideSelfService must be true) and notes it is for the current user, but it does not explicitly contrast with siblings like the admin get_sessions. The guidance 'Prefer connection.workspaceName and connection.appId as stable config' offers configuration advice but not when-to-use vs alternatives. Overall, usage context is implied but not explicitly differentiated.

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 details side effects: increments tokenRevision, revokes Firebase refresh tokens, sets Clear-Site-Data, and notes that the session row is not deleted. However, the internal contradiction 'without revoking it' conflicts with the stated revocation of Firebase tokens, which would mislead an agent about the exact behavior. Since annotations are absent, this contradiction is a notable transparency flaw.

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 structured with bold headings, bullet points, and clear sections for behavior and source. It is somewhat lengthy but each part adds value, including the browser warning and requirements. Some redundancy appears between the opening summary and the bullet points, but overall it's well-organized.

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?

Despite no output schema, the description explains the endpoint source, required authentication, side effects, and browser-specific caveat. It lacks response format or error conditions, but for a logout operation the response is typically minimal. The internal contradiction about revocation and incomplete parameter coverage prevent a perfect score.

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

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

With 0% schema coverage, the description adds meaning to auth.sessionToken by noting it's sent as a Bearer token, and suggests using connection.workspaceName/appId as stable config. However, it does not describe body, query, or params (though they may be empty), leaving some parameters unexplained. The added value is partial, so a baseline of 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 clearly identifies the tool as logging out the current session by invalidating the sessionToken and revoking Firebase refresh tokens. It also distinguishes from the GET logout redirect helper. However, the opening phrase 'without revoking it' is confusing and counteracts the explicit detail that Firebase refresh tokens are revoked, which temporarily muddles the purpose.

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 explicit guidance on when not to use this tool (via XHR/fetch from different origins) and names a specific alternative (GET /api/v1/auth/logout redirect helper). It also states the auth requirement (sessionToken as Bearer token) and recommends stable config fields, giving the agent clear context for use.

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 outlines the main side effects: verifying the token, creating a session, storing serialized payload, and returning a JWT. It also mentions best-effort persistence of email. However, it does not cover potential failure modes or rate limits, but given no annotations, it offers sufficient transparency for a create operation.

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

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

The description is a bit lengthy but well-organized into clear sentences, with a separate 'Prefer' note and source line. It avoids redundancy and packs information efficiently without being overly verbose.

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

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

Given the lack of an output schema, the description adequately explains the return value (sessionToken) and side effects. It could mention error handling or idempotency, but it covers the essential context for a create-and-return operation.

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

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

The description enriches the schema by explaining defaults (payload defaults to {}), constraints (app_id must belong to workspace), and relationships (connection fields provide defaults for hosted login). This adds meaning beyond the terse schema descriptions.

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 creates a new session, identifies the primary inputs (Firebase ID token, workspaceName, payload), and contrasts with the get_or_create sibling by explicitly saying 'Prefer POST /sessions/get-or-create for hosted-login-style flows that should reuse an active session.' This makes its purpose distinct.

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 provides explicit when-to-use guidance: use this for creating a brand-new session, and recommends the get_or_create alternative for reuse scenarios. It also specifies prerequisites like needing a Firebase token and workspaceName, making usage conditions 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 full burden and excels: discloses payload is ignored on reuse, new row creation with 1-hour TTL, best-effort email backfill, requires auth.firebaseToken, and touches activity. It also notes the token is forwarded as a Bearer token and the source endpoint.

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 with a lead sentence summarizing core behavior, followed by critical edge cases, then configuration advice. Each sentence adds value, though it is a bit long; the markdown line breaks help readability.

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 nested objects, no output schema, and no annotations, the description covers core logic, parameter interactions, authentication requirements, TTL, email backfill, and integration best practices. It is complete and actionable for an agent.

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

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

Although schema coverage is 0%, the description explains key parameter semantics: workspaceName scopes the session, payload is ignored on reuse, auth.firebaseToken is required, and connection.workspaceName/appId are preferred stable config. It adds nuance beyond the schema (e.g., 'payload is ignored on reuse') but doesn't enumerate every 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 it verifies Firebase tokens, reuses an active session for (workspaceName, Firebase UID, app_id), and returns a new sessionToken JWT, otherwise creates a new session. It distinguishes itself from the sibling POST /sessions by explicit scoping and 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?

Provides explicit guidance on when to use this tool vs. alternatives, such as 'Prefer a dedicated app_id per integration surface, or revoke old sessions' and 'Prefer connection.workspaceName and connection.appId as stable config'. It also explicit says 'Otherwise behaves like POST /sessions' to set expectations.

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 burden of behavioral disclosure. It discloses critical behaviors: that JWT expiry is not enforced on the internal session token (only signature and tokenType are validated), that tokenRevision is incremented invalidating previous tokens, that server-side expiry is extended by 1 hour, and that Firebase email may be backfilled. This is substantial transparency for a mutation operation, though it does not explicitly state that this is a write operation or its side effects on other sessions, but it covers the main behavioral expectations.

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 with a clear flow: first explains the verification and validation process, then the token invalidation mechanism, then the return values, then the email backfill, and finally the usage path. It is detailed yet organized in logical paragraphs. It could be slightly more concise by trimming some redundancy (e.g., repeating 'sessionToken' details), but it is generally efficient and earn its content.

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's complexity (token renewal with multiple security and state changes) and the absence of output schema and annotations, the description provides a comprehensive understanding of the tool's behavior: what inputs are needed, what happens internally, and what is returned. It lacks explicit information on potential error cases (e.g., mismatched UID) but covers the main functionality. It also adds usage guidance about URL encoding and Bearer token. Overall, it is complete for an agent to correctly invoke and understand the 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 schema description coverage is 0%, so the description must compensate. It explains the key parameter sessionToken in detail, including its purpose and URL-encoding requirement. It also mentions auth.firebaseToken as required. However, it does not explain the connection parameters (host, appId, workspaceName) or the body/query objects, which are part of the schema. Since the description adds value for the most critical parameters but leaves others undocumented, it partially compensates but not fully.

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's purpose: renew a session JWT by verifying a Firebase ID token and parsing the sessionToken path parameter as an internal SESSION JWT, returning a new session token and payload. It uses a specific verb ('renews', 'verifies') and resource ('session JWT'), and distinguishes itself from siblings like post_sessions_revoke or get_sessions by focusing on token renewal. The main functionality is unambiguous and complete.

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 clear usage context: it specifies the exact path form (POST /api/v1/sessions/renew/{sessionToken}) and emphasizes URL-encoding the JWT, which is a practical implementation guideline. It also mentions requiring auth.firebaseToken and forwarding as a Bearer token. However, it does not explicitly state when NOT to use this tool versus alternatives (e.g., when to use post_sessions_revoke instead), so it lacks explicit exclusions but still gives meaningful usage direction.

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 transparency burden. It discloses that the tool revokes the session, requires `auth.sessionToken`, and forwards it as a Bearer token. It does not explain whether the revocation is irreversible, what permissions are needed, or what side effects occur beyond the session being revoked, leaving some behavioral ambiguity.

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 behavior and then adds endpoint, authentication, and configuration context. It is concise overall, though the final sentence about preferring stable config feels somewhat tangential to the revoke operation and slightly dilutes the focus.

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 output schema and no annotations, the description is adequate but minimal. It provides the action, endpoint, auth requirement, and a use case, but does not distinguish itself enough from `post_sessions_revoke_session_id`, nor does it clarify required host configuration or the broader request lifecycle. It is enough to invoke the tool, but not fully complete for a mutation tool with this parameter surface.

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

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

With schema description coverage at 0%, the description must compensate for parameter documentation. It adds meaning for `auth.sessionToken` by explaining it is forwarded as a Bearer token, and it comments on `connection.appId` and `connection.workspaceName`. However, it does not explain the required `connection.host` or the role of `body`, `query`, and `params`, leaving the parameter semantics partially incomplete.

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

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

The description uses a specific verb and resource: 'Revokes the session referenced by the internal SESSION Bearer token.' It clearly identifies the tool's behavior and distinguishes it from the sibling tool `post_sessions_revoke_session_id`, which revokes by session ID rather than by token.

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 a clear usage context: it says this is 'useful for automation clients that only hold a session token and want to revoke it cleanly.' However, it does not explicitly name an alternative tool or state when not to use this one, so it lacks full exclusionary 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?

No annotations are provided, so the description carries the full burden. The description mentions required auth (auth.userToken forwarded as Bearer token) and the prerequisite enableSelfService, but it does not disclose the effects of revocation (e.g., if the session is immediately invalidated, if there are side effects on tokens), nor does it mention error conditions or rate limits. It also adds a note about using connection.workspaceName and appId as stable config, but that is more of a config guideline than a behavioral transparency.

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 relatively concise (three sentences) and front-loads the key purpose. The note about stable config is arguably unrelated to the tool's main function and could be omitted, but it does not significantly hurt readability. It could be more useful to explain the sessionId parameter semantics instead.

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 that the tool is a mutation (revoke) and has no output schema, the description should explain the result of the operation, error cases, and side effects. It also lacks details on the meaning and constraints of the sessionId parameter. The description is incomplete for a destructive operation.

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

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

Schema description coverage is 0%, meaning the description adds no parameter-level detail. The description does not explain the meaning of sessionId, connection fields, or auth fields beyond what the schema provides (which is minimal). With 5 parameters and zero coverage, the description fails to compensate for the schema's sparse parameter documentation.

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 title and description clearly identify the tool as revoking a session owned by the current user. It mentions the HTTP method and endpoint path (POST /api/v1/sessions/revoke/{sessionId}) and contextualizes it as a self-service dashboard endpoint. However, it does not distinguish from the sibling tool post_sessions_revoke, which likely performs a similar revoke action.

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 states when to use it: it is a self-service dashboard endpoint, requires workspace enableSelfService: true, and is for revoking a session owned by the caller. It does not explicitly say when not to use it or mention alternatives, but it does provide clear context and prerequisites.

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 burden. It discloses that the session is encrypted and returns the updated decrypted payload, and mentions the unwrapping of the JSON body. However, it doesn't mention idempotency, error conditions, or side effects beyond the stated return, which is acceptable for a set operation.

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 three focused sentences: the core behavior, the body format, and a usage note. Every sentence adds relevant information without redundancy. It's front-loaded and efficient.

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

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

The tool has 5 parameters with some nested objects and no output schema. The description covers the key semantic aspects (setting a key, return behavior, auth token) and provides a practical tip. It lacks some param details, but the essential behaviors are documented.

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 only 20%. The description explains the body format (`{ "value": <x> }` unwrapped) and the 'key' param, but omits details on auth and connection params. It adds value for the body and key but doesn't fully compensate for the low coverage on other params.

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 ('Sets') and resource ('key in the encrypted session payload'), clearly distinguishing it from siblings like delete_sessions_delete_key and get_sessions_get_key. It also explains the payload unwrapping behavior and the source endpoint.

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 notes the requirement for auth.sessionToken and suggests preferring connection.workspaceName and connection.appId for stable config, which provides context on when to use this tool. It doesn't explicitly state when not to use it, but the source endpoint and payload handling imply usage in session manipulation.

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 delivers: no token needed, always targets /app/sessions/login, never the legacy console URL, and hand-built URLs cause login-loop and stale-renewal bugs. This goes well beyond the schema and gives the agent critical operational detail.

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 its core purpose and then adds precisely the constraints, timing, and anti-patterns the agent needs. Every sentence earns its place; no fluff or repetition.

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 builder tool with no output schema and no annotations, the description is self-sufficient: it covers prerequisites, correct target, exclusion of the legacy path, common failure mode, and explicit alternative. The agent can confidently invoke the tool correctly from the description alone.

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%, with rich parameter-level descriptions such as the intent enum semantics and expiredToken caveats. The tool description itself doesn't add parameter-specific detail, so the baseline of 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 clearly states that the tool 'Builds a correct hosted-login redirect URL' and explicitly scopes it to /app/sessions/login session apps, while ruling out the legacy /app/login console URL. This distinguishes it from login-related siblings and the logout URL builder.

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 says this requires no secureFlows token and is safe to call at app-scaffolding time before any user session exists, identifying the exact phase when it should be used. It also gives strong when-not-to-use context by warning against the legacy console URL and hand-building the URL with URLSearchParams.

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 full burden and delivers extensively: it warns about two logout anti-patterns (callback loops and session_token renewal), explains why fetch/XHR fails (cookie survives), and states it never handles revoke due to destructive consequences. This is exemplary transparency.

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 concise for the complexity, with three focused paragraphs: first the core behavior, then navigation caution, then revoke exclusion. Every sentence adds value, and it starts with the primary purpose. No fluff or 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 the security-sensitive nature, no annotations, and no output schema, the description fully covers what the tool returns (a URL), constraints on inputs, and behavioral caveats. It is complete enough for an agent to use safely and correctly without additional context.

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 already documents all three parameters (100% coverage), the description adds critical constraints beyond the schema: postLogoutRedirectUri must not be /callback and must not contain session_token, and the origin is prod-fixed. This enriches parameter meaning substantially, aiding correct invocation.

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 "Builds a correct redirect-logout URL" and explicitly differentiates it from logout execution tools like post_auth_logout by focusing on URL construction. It also distinguishes from login URL builder and revoke tools, making its purpose unambiguous.

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

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

The description explicitly says when not to use the tool: "never builds a revoke request" and clarifies revoke is only for account deletion. It also explains that top-level navigation is required (not fetch/XHR) for correct behavior, giving clear context on how to use the generated URL. This is high-quality 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 honestly discloses its heuristic nature: 'Heuristic text analysis, not a parser or a type checker. It can miss things it has no rule for, and a project check can be satisfied by the right keyword in the wrong place.' It also explains the two result scopes (file and project) and the meaning of 'error' vs 'needs_review', setting clear expectations.

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 organized into short paragraphs, each conveying a distinct aspect: basic usage, parameter guidance, result scopes, heuristic limitations, and action items. No sentence is redundant; every part earns its place despite the length.

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?

It fully explains what the tool does, how to use it, what results look like (two scopes), its limitations, and how to interpret outcomes ('Fix every error... treat needs_review as a lead'). Although there is no output schema, the description sufficiently covers expected results and next steps.

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 only parameter 'files' is already well-described in the schema as a map of file paths to source code. The tool description adds critical usage nuance: 'Pass every auth/session-related file in one call', which explains why the parameter exists and how to populate it correctly. This goes beyond the schema's basic type definition.

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's function: it checks generated source against secureFlows integration rules. It distinguishes itself from sibling tools (which handle sessions and authentication URLs) by focusing on static analysis of code patterns.

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 tells when to use: 'Checks source you already generated' and instructs to 'Pass every auth/session-related file in one call' because some checks are evaluated across the whole set. It also notes it needs no token and is safe at scaffolding time, providing clear context for appropriate invocation.

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