secure-flows

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

With no annotations present, the description fully carries the burden of behavioral disclosure. It explains session creation vs renewal, payload persistence rules, TTL behavior, email backfill, redirect responses, 400 on disallowed redirect URIs, and error responses that do not redirect. 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 long but well-structured with numbered steps and clear conditional paths. It front-loads the endpoint's role and auth requirement, then details behaviors. Minor redundancy exists around 'No Authorization header is required,' repeated at the end, but overall every major sentence adds necessary information.

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

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

The description is complete for a complex redirect callback with no output schema and no annotations. It covers auth, redirect validation, create/renew semantics, parameter constraints, error behavior, and configuration guidance. An agent has enough information to call this tool correctly and predict its outcomes.

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 substantial meaning beyond the schema: firebaseToken is a Firebase ID token, client_redirect_uri must be allowlisted, session_token triggers renewal, payload is stored only on create, and ttl_seconds applies to both paths. Even with sparse schema coverage, the description compensates fully for every parameter's role.

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 explicitly identifies the tool as a browser redirect endpoint used after hosted /app/sessions/login, names the source route GET /api/v1/auth/callback, and explains the create-vs-renew behavior. This clearly distinguishes it from sibling session management tools like post_sessions_get_or_create and post_sessions_renew_session_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 clear context for when the tool is used: after hosted login, with no Authorization header, and with an allowlisted redirect URI. It does not explicitly list sibling tools to exclude, but the callbacks and error behavior make the usage context unambiguous.

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 the mutating action, the conditional return value ('returns true if the key existed'), the HTTP source, and the authentication requirement ('Requires auth.sessionToken and forwards it as a Bearer token'). It does not discuss error or idempotency behavior, but the core side effects are clear.

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 first sentence is strong and front-loaded. The source and auth lines add useful context, but the final sentence about preferring connection.workspaceName and connection.appId feels tangential and cryptic in the context of deleting a session key, slightly reducing 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?

For a simple delete-by-key tool, the description covers purpose, return semantics, and auth. However, with no output schema and no annotations, it leaves gaps around not-found behavior, error cases, and the required connection.host, making it adequate but not 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 description names the operationally important inputs (`key` and `auth.sessionToken`) in plain language. The schema already documents these fields, along with connection properties, so the description adds modest value but does not fully compensate for the low schema description coverage of the connection/body/query scaffolding.

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 a specific verb-resource pair: 'Removes `key` from the session payload' and clarifies the return value. This clearly distinguishes the tool from siblings like post_sessions_set_key and get_sessions_get_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?

There is no explicit statement about when to use this tool versus alternatives such as post_sessions_set_key or get_sessions_get_key. The stable-config note about connection.workspaceName and connection.appId is not usage guidance for deletion, so the agent is left to infer when this tool should be chosen.

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 fully discloses behavior: it is best-effort and idempotent, invalidates token via tokenRevision, handles already-expired sessions without 401, revokes Firebase tokens, sets Clear-Site-Data, and redirects. No behavioral aspect is left undisclosed.

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 bullet points and clear sections (purpose, critical rules, behavior). Every sentence serves a purpose—no fluff. It is front-loaded with the primary purpose and usage constraint before behavioral 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 complex tool with nested input objects, zero annotations, and no output schema, the description covers all necessary context: endpoint source, client requirements, behavioral semantics, and redirect expectations. An agent can call it correctly without additional information.

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?

Though the schema includes descriptions, the tool description goes further by relating session_token and redirect_uri to usage rules (e.g., never put token in redirect_uri). It adds critical context about what each parameter does in the logout flow, compensating for the low schema coverage signal.

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: a browser-friendly logout endpoint for cross-site clients that invalidates a session token, clears cookies via Clear-Site-Data, and redirects. It differentiates itself from siblings by emphasizing the first-party baking context and navigation-only usage, making it distinct from post_auth_logout or URL builders.

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 directs use as top-level navigation, not XHR/fetch, and provides critical client rules (clear sessionToken before, never include session_token in redirect_uri). It also notes no Authorization header is required, and gives a preference for stable config fields, which guides the agent on when and how to call.

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 disclosure burden. It does so well by naming the embedding model, the pgvector index, the read/search nature of the call, and the auth requirement. It stops short of describing rate limits or error behavior, but for a search tool the core behavior is transparent enough.

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 well structured: it front-loads the core behavior, then gives the endpoint, auth requirement, and config guidance. Every sentence earns its place, with no filler or redundant restatement of the tool name.

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

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

For a 5-parameter nested tool with no annotations and no output schema, the description provides the endpoint, behavior, and auth context, but omits the output shape, limit semantics, and empty/error result behavior. It is sufficient to attempt a call, but not fully complete for an agent that needs to interpret results robustly.

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% at the top-level parameter envelope, so the description must compensate. It only adds guidance about connection.workspaceName and connection.appId, and does not explain the meaning of q, limit, host, or the body/params fields. The agent is left to infer parameter semantics from nested schema text rather than from the tool description.

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

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

The description clearly states a specific verb and resource: it embeds the query with Ollama and returns the closest public doc chunks from the pgvector search index. It also names the underlying endpoint, making the tool's job unambiguous and distinct from the auth/session siblings.

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

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

The description gives clear context: it is a semantic documentation search, requires no Authorization header, and recommends using connection.workspaceName and connection.appId as stable config. It does not explicitly name excluded alternatives, but no sibling tool is a competing docs-search tool, so the absence of direct alternative routing is not a serious gap.

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 that it returns a decrypted payload, is a read operation, requires auth.sessionToken forwarded as a Bearer token, and specifies the response shape (flat JSON, empty {} for empty payload). It doesn't mention error handling, rate limits, or token expiration, but the core behavior is covered. This is adequate but not comprehensive.

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

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

Four sentences, each with a distinct purpose: core action, response shape, auth mechanism and source, and a config recommendation. The most important information is front-loaded. Zero filler 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?

For a tool with no output schema, no annotations, and many siblings, the description covers the main purpose, response shape, and auth requirement. However, it lacks any comparison with the numerous sibling session tools, so an agent might select the wrong one without deeper inspection. It doesn't describe the payload contents beyond 'flat JSON object,' which might be insufficient for some uses. Overall, it's functional but not fully complete for correct sibling selection.

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 describes all parameters (auth.sessionToken, connection.host, etc.), so the baseline is 3. The description adds a useful tip about preferring workspaceName and appId for config, and reiterates the sessionToken requirement. It doesn't add syntax or format details beyond the schema, but the extra guidance on connection fields is valuable. Overall, it meets the baseline.

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

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

The description states a clear verb and resource: 'Returns the decrypted session payload for the authenticated internal session token.' This is specific and distinguishes it from tools like get_sessions_my or get_sessions_identity, though it doesn't explicitly name them. The source endpoint adds clarity. However, it doesn't directly contrast with siblings, so it falls short of a 5.

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

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

There is no explicit guidance on when to use this tool versus other session-related siblings. The only guidance is 'Prefer connection.workspaceName and connection.appId as stable config,' which is about parameter usage, not tool selection. The description implies it's for retrieving the current session payload but doesn't state when an agent should choose this over get_sessions_my or get_sessions_identity.

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 provides meaningful details: 404 signals a never-written key and should not be treated as an error, auth.sessionToken is required and forwarded as a Bearer token, and the payload value is decrypted. It does not describe success response shape or other error cases, so it is not a 5, but it is strong for a simple read tool.

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 purpose is front-loaded in the first sentence and the description is compact, with the 404 warning clearly bolded. The final preference sentence is slightly tangential to invoking this specific tool but still relevant to integration quality.

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 core invocation details and the notable 404 behavior. However, there is no output schema and no annotation, and the description does not indicate what a successful response looks like or how to handle auth/connection failures; it also says auth.sessionToken is required while the schema marks `auth` itself optional. These gaps leave an agent with reasonable but incomplete guidance.

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

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

Schema coverage is 0%, so the description must compensate. It clarifies the `key` parameter as the payload key, explains the `auth.sessionToken` requirement and Bearer forwarding, and advises stable `connection.workspaceName`/`appId` usage. It does not cover `connection.host` or body/query, but the schema itself describes host and body/query are empty.

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 'Retrieves the decrypted payload value for `key`', which names a specific verb, resource, and the parameter involved. It is clear about what the tool does, but it does not explicitly differentiate this from siblings such as get_sessions or get_sessions_identity, so it misses the top criterion for 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 no guidance about when to choose this tool over alternatives and never names a sibling. The note about preferring connection.workspaceName/appId is configuration advice, not tool-selection guidance; the 404 note is error handling rather than 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?

The description discloses the return values, notes that email is best-effort and may be null, and mentions the underlying endpoint and authentication requirement. It does not describe error conditions or rate limits, but for a simple identity getter the behavior is sufficiently transparent. Annotations are absent, so the description carries the full burden, but it covers the essential behavioral aspects.

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 into clear paragraphs with bold emphasis on key terms like userId and email. It is slightly verbose but each sentence adds meaningful information—no filler. The length is acceptable given the nuance about identifier stability and email best-effort behavior.

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 retrieval tool, the description covers the purpose, usage, parameter semantics, and return behavior. It does not specify an output schema (none is provided) or error handling, but within the given scope it is fairly complete. The distinction from sibling tools (e.g., get_sessions_my) is implied through the emphasis on the end-user identity vs. session details.

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 explains the role of auth.sessionToken (required, forwarded as Bearer) and connection.workspaceName/appId (defaults). It does not explicitly address body, query, or params, but these are likely unused for an identity endpoint per the schema. The schema itself provides descriptions for sessionToken, host, appId, and workspaceName, complementing the tool description. Overall, parameter usage is reasonably well documented.

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: it returns the workspace end-user's userId and email for the authenticated session token. It also specifies what it does not return (Firebase UID or session payload) and provides a concrete use case (correlation key for backend webhooks). This leaves no ambiguity about the tool's function.

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 guidance on when to use this tool: 'Use it as the correlation key when your own backend needs to link an external event back to this user.' It also explains why not to use session token or session id for this purpose (they expire/rotate), which directly addresses alternative tool choices. This makes the 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 provided, the description carries the full burden, and it does so thoroughly. It discloses the self-service prerequisite, the conditional payload inclusion for active-status rows, pageSize clamping, the fact that auth.userToken is forwarded as a Bearer token, and the source endpoint. This is rich, operationally meaningful behavioral disclosure.

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 behavior in the first sentence. Each subsequent sentence adds a distinct operational fact: prerequisite, payload rule, sort/page behavior, source, auth, and config guidance. No filler or repetition is present.

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 endpoint's paging/sorting/filtering complexity and the absence of annotations, the description covers the critical invocation facts: auth requirements, workspace prerequisite, pagination behavior, filter semantics through schema, and config guidance. It does not detail the exact page response shape, but for a read-only paged list the provided operational details are sufficient 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?

The description adds meaning not obvious from the schema: pageSize is clamped to 1–200 with default 20, sort keys mirror the admin list, auth.userToken is forwarded as a Bearer token, and connection.workspaceName/appId are recommended as stable config. It does not restate every nested query filter, but those are already described in the schema, so the added operational context earns above-baseline credit.

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 verb and resource: it 'Returns a page of sessions for the current user within the current workspace.' It also positions itself as a self-service dashboard endpoint, which separates it from the admin-oriented sibling get_sessions. This is clearly more than a restatement of the title.

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 for when this endpoint is appropriate: it is self-service, requires workspace enableSelfService: true, and targets the current user's sessions. It also advises preferring connection.workspaceName and connection.appId as stable config. However, it does not explicitly name alternatives or state 'use get_sessions for admin lists,' 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 full disclosure burden, and it delivers: it states tokenRevision increment, no new token issued, Firebase refresh-token revocation, Clear-Site-Data cookies, and that the session payload/row are not deleted. It also flags cross-origin limitations, which is valuable behavioral context.

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 a warning and then uses tight bullets for behavior, making the important side effects scannable. The opening 'without revoking' ambiguity and the trailing generic config sentence keep it from being fully sharp.

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

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

For an auth mutation with no annotations and no output schema, the description covers the action, prerequisites, side effects, browser caveat, and preferred alternative. An agent has enough information to decide when to call it and what to expect.

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 behavioral meaning not visible in the schema: auth.sessionToken is required and forwarded as a Bearer token, and connection.workspaceName/appId are recommended as stable config. It does not enumerate every parameter, but the remaining body/query/params are empty objects, so little is missing.

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 identifies a concrete action — logging out the current session — and names the counterpart GET redirect helper, so an agent can connect the tool to logout behavior. The opening phrase 'without revoking it' is ambiguous against the title's 'revoke Firebase refresh tokens' and the later revokeRefreshTokens bullet, which slightly muddies what exactly is and isn't revoked.

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 warns that XHR/fetch from a different origin is unreliable for clearing hosted-login cookies and directs browser apps, especially localhost, to the GET /api/v1/auth/logout redirect helper. This gives the agent a concrete condition for choosing an 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 provided, the description carries the full burden and does an excellent job: it discloses auth token requirements, Bearer forwarding, payload defaulting, JWT return semantics, TTL, and a best-effort side effect on the workspace end-user row. This goes well beyond what the schema or annotations reveal.

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, labeled sections and front-loads the core behavior in the first sentence. It is slightly dense but every sentence adds useful information, such as TTL, email persistence, source route, and configuration guidance.

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 and no annotations, the description covers the endpoint, authentication, key parameters, return value, side effects, and an alternative tool. It does not detail the full response shape or error behavior, but for a session-creation tool the provided context is largely sufficient.

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 meaningful semantics for the key parameters: `auth.firebaseToken` is required and forwarded as a Bearer token, `workspaceName` scopes the session, `payload` defaults to `{}`, and `connection.workspaceName`/`connection.appId` serve as stable config. It does not explicitly describe `app_id` or `host`, but the schema already provides descriptions for those, so the main call parameters are well covered.

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: it verifies a Firebase ID token, creates a session for `workspaceName`, stores `payload`, and returns `sessionToken`. It also names the sibling alternative `POST /sessions/get-or-create`, distinguishing this tool from the get-or-create variant.

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 to prefer `POST /sessions/get-or-create` for hosted-login-style flows that should reuse an active session, giving concrete routing guidance. It also advises using `connection.workspaceName` and `connection.appId` as stable config rather than generating identity fields dynamically.

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 and does so thoroughly. It discloses that the tool touches activity, does not create duplicates, uses a default 1-hour TTL, forwards the Firebase token as a Bearer token, and best-effort persists email. These are critical behavioral details that an agent needs to invoke correctly.

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 every sentence contributes new information: reuse key, payload behavior, defaults, auth, and configuration guidance. It is front-loaded with the core behavior and then adds necessary details. No filler 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 complexity (reuse-vs-create, side effects, auth, defaults), the description is complete. It explains the return value (sessionToken JWT), behavior on reuse, the default TTL, and the auth requirement. There is nothing essential missing for correct invocation.

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

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

Schema description coverage is 0%, so the description must fully compensate. It explains the meaning and role of workspaceName, app_id, and payload (including that payload is stored as {} if null, and that app_id is per-app policy). It also clarifies that connection.workspaceName and connection.appId serve as stable defaults. This provides comprehensive meaning for all parameters beyond the 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 the tool verifies a Firebase ID token and either reuses an active session or creates a new one. It defines the exact key (workspaceName, Firebase UID, app_id), the reuse behavior, and differentiates itself from POST /sessions. The purpose is unambiguous and specific.

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 explains when payload is ignored (on reuse) and when it applies (new session), and provides guidance to use a dedicated app_id or revoke sessions when a fresh payload is needed. It also advises on stable config (connection.workspaceName, connection.appId). This gives clear when-to-use and when-not-to-use direction beyond the schema.

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 thoroughly. It discloses side effects (tokenRevision increment invalidates older session JWTs), validation checks (signature, tokenType=SESSION, Firebase UID match), expiry extension, email backfill, and auth forwarding as Bearer.

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 path form, encoding, auth, and configuration. It is longer than a minimal description, but the extra sentences earn their place; only the final generic config sentence feels slightly 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 mutating auth operation with no output schema, the description is remarkably complete: it gives the path, HTTP method, auth requirement, URL-encoding, return values, side effects, and validity duration. An agent has enough to invoke it correctly without guessing.

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 important semantics beyond the schema: sessionToken must be URL-encoded in the path, may be expired, and is parsed without expiry enforcement; auth.firebaseToken is forwarded as a Bearer token. It could have also elaborated on connection.appId/workspaceName usage, but the schema descriptions cover those basics.

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: verify the Firebase ID token, consume an internal SESSION JWT from the sessionToken path segment, increment tokenRevision, and return a new sessionToken. It is clearly distinct from sibling tools like revoke or get_or_create because it focuses on replacing an existing token without enforcing JWT expiry.

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 makes the intended use apparent: renew an expired or expiring session JWT, since JWT expiry is explicitly not enforced and server-side expiry is extended by one hour. It does not explicitly name sibling alternatives or state when not to use it, but the context is clear enough for an agent to select 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, the description carries the burden and does disclose the key behavior: revocation of the session identified by auth.sessionToken, forwarded as a Bearer token. It does not state irreversibility, idempotency, or response/error behavior, which leaves a meaningful transparency gap for a destructive auth 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 key action is front-loaded in one sentence, followed by a relevant use case, source endpoint, and auth requirement. The final 'prefer stable config' sentence is somewhat peripheral to this specific endpoint, but the overall description stays compact.

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

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

For a destructive auth tool with no annotations and no output schema, the description should explain the side effects and expected result of revocation. It omits what happens to the token/session after success, error conditions, and how this differs from revoke_session_id, so it is not complete enough on its own.

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?

It adds semantic value for auth.sessionToken by explaining that it is forwarded as a Bearer token, and gives stable-config guidance for connection.workspaceName/appId. It does not describe the required connection.host or address the empty body/query/params containers, so it only partially compensates for the low schema description 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 opens with a precise action and resource: it revokes the session referenced by the session token, and the title reinforces the 'current session' scope. This distinguishes it from sibling post_sessions_revoke_session_id, which revokes by session id.

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 identifies the audience and context: automation clients that only hold a session token and want to revoke it cleanly. It does not state when not to use it or explicitly name the session_id alternative, so it stops short of full routing 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 provided, the description carries the full burden. It discloses authentication (Bearer token) and the enableSelfService prerequisite, but it does not explicitly state the irreversible effect of revoking a session or any consequences. For a destructive operation, more explicit side-effect disclosure would be expected.

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 exceptionally concise—three short sentences plus a source line. It is front-loaded with the purpose, then covers prerequisite, auth, and config advice. No filler 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?

For a tool with nested parameters, no output schema, and no annotations, the description omits critical details: the meaning of sessionId, the response format, error behavior, and idempotency. It provides some context but is far from sufficient for an agent to invoke it with confidence.

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% from the description, and the description does not explain the sessionId parameter at all. It mentions auth.userToken and connection fields but leaves sessionId completely undefined. The schema itself lacks a description for sessionId, so the description fails to compensate for that 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 the action (revoke), the resource (a session), the ownership scope (owned by the caller in the current workspace), and even includes the source endpoint. It distinguishes the tool from siblings like post_sessions_revoke by highlighting the self-service and caller-owned nature.

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 context (self-service dashboard, enableSelfService requirement, caller-ownership) and some config guidance, but it does not explicitly contrast this tool with alternative revoke tools or state when not to use it. The guidance is mostly implied rather than 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 carries the full burden of behavioral disclosure. It reveals that the payload is encrypted, that the body is unwrapped when sent as { "value": <x> }, that the response is the updated decrypted payload, and that auth.sessionToken is forwarded as a Bearer token. This goes well beyond the name and schema, though it does not discuss overwrite semantics, persistence, 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?

The description is concise and front-loaded with the core behavior, then adds the body format, source route, auth requirement, and a config best practice. Each sentence earns its place; only the 'Prefer connection.workspaceName...' sentence is slightly tangential but still useful. No filler 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?

For a state-changing tool with five parameters and no output schema, the description covers the essential call semantics: what is set, how the body is interpreted, what authentication is needed, and what is returned. It could additionally describe when to prefer get/delete siblings, but the provided context is sufficient for basic correct invocation.

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

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

Schema description coverage is only 20%, so the description needs to compensate. It does add meaning by explaining the body { "value": <x> } unwrapping and identifying params.key as the payload key, and it clarifies the auth token requirement. However, other parameters such as connection.host and query are left to the schema or undocumented, so coverage remains 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 the action: 'Sets a key in the encrypted session payload and returns the updated decrypted payload.' This is specific about the verb, resource, and side effect, and it distinguishes the tool from sibling get_sessions_get_key and delete_sessions_delete_key. The body-unwrapping detail further clarifies exactly 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 implies usage: use this when you need to set a key in the session payload. It provides some contextual guidance by requiring auth.sessionToken and recommending stable connection.workspaceName/appId fields, but it does not explicitly contrast with sibling get/delete tools or state when-not-to-use it. The guidance is more about configuration than tool selection.

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 takes on full behavioral disclosure and does it well. It reveals that no token is required, that the tool targets the session-login endpoint, that it never returns a legacy firebaseToken, and that using the wrong URL causes an infinite redirect loop. These are meaningful behavioral traits beyond simply "builds a URL."

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. Every sentence earns its place: safety timing, endpoint selection, legacy-URL risk, and the hand-building pitfall. There is no filler 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 6-parameter tool with no output schema and no annotations, the description is largely complete: it covers when to call it, why it is safe, what endpoint it targets, and what failure mode it prevents. The only minor gap is that it never explicitly states the return value is the redirect URL string, although that is strongly implied by "Builds a correct hosted-login redirect URL."

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%, and the schema itself already provides rich parameter explanations, including intent semantics, origin constraints, and expiredToken warnings. The description adds high-level context but does not materially extend the per-parameter meaning, so the baseline score 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 starts with a specific verb and resource: "Builds a correct hosted-login redirect URL." It further distinguishes itself by stating it "Always targets /app/sessions/login" and explicitly "Never builds the legacy /app/login console URL," which separates it clearly from secureflows_build_logout_url and prevents confusion with legacy 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?

The description gives a clear when: "safe to call at app-scaffolding time, before any user session exists." It also names the common alternative mistake, "hand-building the URL with URLSearchParams," and tells the agent to use this tool instead. It does not explicitly list exclusions such as "use secureflows_build_logout_url for logout," but the context and sibling names make the intended usage fairly 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 provided, the description fully carries the burden of behavioral disclosure. It reveals the two anti-patterns it refuses, explains the silent re-authentication risk, and states that it always instructs top-level navigation rather than fetch/XHR. This is extensive, security-relevant transparency with no contradictions.

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, well-structured paragraph that front-loads the core purpose and then layers constraints with clear causal reasoning. It is lengthy but every sentence carries security-critical information, with no fluff or repetition. The structure flows logically from purpose to exclusions to behavioral requirements.

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 no output schema, and while the description explains the navigation behavior of the result, it does not explicitly state that the output is a URL string. Given the security-critical nature, the description covers the key constraints and exclusions comprehensively, but an explicit statement of the return format 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?

Schema coverage is 100%, and each parameter already has a descriptive explanation—postLogoutRedirectUri even includes the anti-pattern constraints. The tool description adds rationale behind those constraints but does not introduce new syntax or formats. Given the schema already does the heavy lifting, a baseline of 3 is appropriate; the description adds context but not new parameter-level information.

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 ('Builds a correct redirect-logout URL') and explicitly distinguishes itself from revoke by stating 'This tool never builds a revoke request.' It also differentiates from a login builder by focusing on logout anti-patterns, making its purpose unambiguous even among many siblings.

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

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

The description explicitly states when NOT to use this tool (never for revoke, which is reserved for 'delete my account') and implies use for ordinary sign-out. It also specifies the top-level navigation requirement. However, it does not name alternative logout tools like post_auth_logout or get_auth_logout, leaving minor ambiguity about choosing among them.

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. It clearly discloses that this is heuristic text analysis, not a parser or type checker, that it can miss issues, and that project-scope findings are absence-based rather than forbidden patterns. It also explains the error vs needs_review handling.

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?

Although the description is long, every section earns its place: the first paragraph states purpose and usage, the second details finding scopes, and the third covers limitations and actionability. The most important constraints are 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 is complete for a static linter with one parameter and no output schema. It explains input, finding categories, limitations, and expected action on results. An agent has enough context to invoke it correctly and interpret its output.

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 map well, but the description adds critical semantic context: cross-file evaluation means callers must pass the whole auth/session-related file set in one call. It also clarifies the practical meaning of the input ('source you already generated') beyond bare schema types.

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 a specific verb and resource: 'Checks source you already generated against the secureFlows integration rules.' It clearly distinguishes itself from sibling tools like auth_session_callback and secureflows_build_login_url, which are runtime/auth tools rather than static analysis.

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

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

Explicitly states when it is safe and appropriate ('Needs no secureFlows token; safe at scaffolding time'), how to batch input ('Pass every auth/session-related file in one call'), and what it is not for ('not a substitute for the Agent implementation checklist... not for the checks that need a running app').

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