brainkb

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

With no annotations at all, the description carries the full burden of disclosing behavior. It does state it 'sets the JWT user active', which reveals the internal mechanism, but it omits critical details such as whether the operation is idempotent, what happens if the user is already active, or any side effects on existing sessions. For an admin mutation, this is insufficient.

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, front-loaded sentence that starts with the '(Admin)' qualifier and immediately states the action. There is no fluff or repetition, every word earns its place.

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

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

For a simple one-parameter admin tool, the description provides the essential action and admin context. However, with no output schema and no annotations, it lacks information about the result of the operation, error conditions, or interaction with related account states. It is minimally adequate but has clear gaps.

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

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

The schema has a single 'email' parameter with no description (0% coverage). The description adds 'by email', clarifying that email is the lookup identifier, which is useful. However, it doesn't provide format expectations or edge-case behaviors, so it partially compensates for the schema gap 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 a specific action: 'Activate a user's account' with the mechanism 'by email'. The verb 'activate' is precise and distinguishes this from siblings like deactivate_user and ban_user. The '(Admin)' prefix adds a clear access context.

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 '(Admin)' label implies this tool is for administrators, giving some usage context. However, there is no explicit guidance on when to prefer this over related tools (e.g., unban_user) or any exclusions. The when-to-use is only implied by the tool's name and purpose.

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 that only matching callers may perform the action, that the space owner and Admin/SuperAdmin always bypass (no lockout), and how 'space_role' matching works (>=). This is substantial beyond the schema, though it does not mention reversibility or duplicate 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?

The description is well-structured: it starts with a parenthetical role qualifier, defines the operation, enumerates parameter values in compact bullet-like lines, explains behavioral implications, and ends with a concrete example. Every sentence adds value without redundancy.

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

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

Given the tool's moderate complexity (4 required parameters, no output schema), the description covers all essential aspects: purpose, parameter semantics, behavior, and an example. It is self-contained and leaves little ambiguity for an agent invoking it. The only minor gap is the explicit format of 'slug', which is easily inferred from 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?

Schema coverage is 0% and only lists parameter names and unconstrained strings, so the description is essential. It explains valid values for 'action', 'subject_type', and provides an example for 'subject_value'. However, 'slug' is only implicitly defined as the space identifier, and no explicit format is given, so the description does not fully compensate for the schema gap.

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

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

The description states a specific verb ('Restrict') with a clear resource ('a space action') and the object ('to a subject'). It distinguishes from sibling tools that list or remove access rules, and the 'Space manager' prefix adds context. The example further clarifies 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 clearly implies this tool is for adding access rules and provides context on when rules take effect ('When rules exist for an action, only matching callers may perform it'). It does not explicitly mention alternatives (e.g., use list_access_rules to view rules), but the behavior and example give sufficient guidance for correct 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?

With no annotations, the description discloses key behaviors: ownership restriction, global uniqueness, 409 conflict on duplicate, and permanence (no unregister/delete). Also explains governance effects on ingest/read. Excellent coverage of side effects and constraints.

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

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

Three sentences, front-loaded with purpose, then critical constraints. Every sentence adds unique information; 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 no output schema, it omits success response details, but covers authorization, conflict behavior, permanence, and governance side effects. For a registration tool, this is nearly complete, though a brief note on return value would elevate it.

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 description must compensate. It adds meaning for 'named_graph_iri' (globally unique) but leaves 'slug' and 'description' unexplained. Since two of three parameters are not semantically defined, the description only partially compensates for the schema gap.

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

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

States a specific action ('Register a named graph and bind it to a space') with a clear resource and governance purpose. Distinguishes from sibling tools like 'list_registered_graphs' and 'add_space_member' by focusing on graph binding to a space.

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?

Conveys when to use it: to register a graph to a space, with owner/editor restriction. Provides context (uniqueness, permanence) but stops short of explicitly naming alternatives or exclusions. Sibling context makes the intended use clear.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It clearly states the role enum and the owner-only permission, which adds useful context. However, it does not disclose what happens on conflict (e.g., does update replace role?), error conditions, or the effect of the operation beyond the action itself.

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 extremely concise with two short sentences, and every word contributes value. It front-loads the action and role constraint. However, it is arguably too terse for a tool with three parameters and no schema descriptions, though the brevity itself is a positive trait.

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 annotations, no output schema, and 0% schema description coverage, so the description needs to be more complete. It provides the role constraint but does not explain how a space is identified by slug, what 'member_email' refers to, what happens on update, or any error/return behavior. This is insufficient for a mutation operation with multiple parameters.

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 the 'role' parameter with allowed values, but does not explain 'slug' or 'member_email' beyond their property names. The token 'member_email' is self-explanatory, but 'slug' is ambiguous without context. Description covers only one of three 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 uses a specific verb 'Add/update' with a clear resource 'space member', and the role values are explicitly listed. It is easily distinguished from sibling tools like brainkb_add_space_graph or brainkb_assign_role.

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 a critical usage constraint ('Owner only') but does not explicitly state when to use this tool over alternatives such as brainkb_assign_role. No when-not-to-use guidance is given, so usage context is partially implied rather than fully documented.

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

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

With no annotations, the description carries the full burden. It discloses important behavioral traits: admin-only access, user profile prerequisite, and role hierarchy restrictions. However, it does not mention reversibility, what happens if the user or role does not exist, or whether changes take effect immediately. This is adequate but not rich.

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 two sentences, front-loaded with '(Admin)' and all content is useful. No redundancy or filler. Every word contributes to understanding the tool's purpose and constraints.

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 simple 2-parameter schema with no output schema, the description covers the essential context: purpose, prerequisite, and restrictions. It does not describe return values or error behavior, but for this tool's complexity, the provided context is sufficient 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?

The input schema has no parameter descriptions (0% coverage), so the description must compensate. It explains email as the user's email and role with examples ('Lab Member', 'External', custom group), and notes the special Admin/SuperAdmin restriction. This adds meaningful meaning beyond the bare schema.

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

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

The description clearly states the tool's function: 'Assign a role/group to a user by email' with a specific verb and resource. It distinguishes from sibling tools like create_role and remove_role by focusing on assignment to an existing user, and the examples ('Lab Member', 'External', custom group) further clarify scope.

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

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

Provides clear usage context: the (Admin) prefix signals permission level, the prerequisite that the user must already have a profile, and the restriction that Admin/SuperAdmin assignment is SuperAdmin-only. While it doesn't explicitly name alternative tools, the guidance is sufficient for an agent to know when this tool applies.

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 burden. The verb 'List' unambiguously indicates a read-only operation with no side effects. For a zero-parameter tool, this is sufficient behavioral disclosure, though it does not detail the structure of the returned list.

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, compact sentence that front-loads the action ('List') and the scope ('available roles/groups'), and includes the access level prefix. Every word adds value, with no 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 simple zero-parameter listing tool without an output schema, the description clearly states what the tool returns (a list of roles) and who should use it (admins). No further details are necessary for the agent to select and invoke it correctly.

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

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

The input schema has zero parameters, so the description need not elaborate. The baseline score of 4 applies; the description contributes no parameter details because there are none to contribute.

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 the specific verb 'List' and identifies the resource as 'available roles/groups', with concrete examples (Admin, Lab Member, Curator). This clearly distinguishes it from sibling tools like create_role or assign_role, which are about mutation or assignment rather than enumeration.

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 '(Admin)' prefix provides a clear context that this is an administrative operation, implying only admin users should invoke it. However, it does not explicitly mention alternatives or when-not conditions, so the guidance is contextual rather than fully explicit.

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

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

With no annotations, the description carries the full burden and does well: it discloses reversibility, history preservation, absence of hard delete, and role-based limitations. Missing details like session/token effects are minor for a ban 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 two sentences with zero filler, front-loading the primary action and then providing critical context about account removal and permissions.

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 2-parameter admin action, the description covers the essential behavioral and access-control aspects. It lacks output details but no output schema exists, and the missing reason parameter explanation is the main gap preventing a 5.

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

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

Schema coverage is 0% and the description only explains the email parameter implicitly via 'by email'. The reason parameter is completely unexplained, leaving its format or purpose ambiguous. The description fails to compensate for the sparse 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 'Ban a user by email' with specific verb and resource, and adds context that this is the account removal mechanism with no hard delete. This distinguishes it from sibling tools like deactivate_user or unban_user.

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

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

The description explicitly says 'This is how accounts are removed' and notes role restrictions (SuperAdmin-only for banning admins, SuperAdmin cannot be banned). This gives clear usage context, though it doesn't explicitly compare to alternatives like unban_user.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses an important behavioral trait: 'Admin only' indicates an authorization requirement. It also describes the data scope (roles, effective capabilities, delegated grants). However, it doesn't state whether the operation is read-only, what errors might occur, or what happens with invalid inputs. This adds some value but lacks rich 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 concise, consisting of two sentences. The first sentence front-loads the core purpose, and the second adds practical use context. There is no redundant or filler content, making it an efficiently structured description.

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 is low-complexity: one parameter, no output schema, no annotations. The description covers purpose, a usage scenario, admin restriction, and the content of the result (roles, capabilities, grants). While it doesn't describe the exact return format, the description is sufficiently complete for the tool's scope, with only minor gaps around edge-case behavior.

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 has one required parameter 'member' with no description (coverage 0%). The description implies that 'member' refers to the user whose capabilities are being shown, which adds meaning beyond the bare schema. However, it doesn't specify the expected format (e.g., username, email, or ID). The description partially compensates for the missing schema documentation 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 function: 'Show a user's roles, effective capabilities, and delegated grants.' This uses a specific verb and resource, and distinguishes it from sibling tools like brainkb_list_capabilities and brainkb_role_capabilities by focusing on a user's effective permissions. The additional context about checking permissions for actions adds purpose 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 provides a clear usage context: 'Useful to check why someone can/can't create team spaces, ingest, etc.' It explicitly indicates this tool is for troubleshooting permission issues, which helps an agent decide when to use it. However, it does not explicitly mention when not to use it or name alternative tools, so it misses the 'when-not' guidance but still has clear context.

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 burden. It discloses that this is an admin-only operation and gives an example format. However, it does not discuss potential side effects, idempotency, error conditions, or whether existing permissions are overwritten. This is a simple create, but transparency is limited.

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 two sentences with no fluff. The first sentence leads with the action and resource, and the second provides a concrete example and a useful note about role attachment. Every sentence earns its place, making it concise and well-structured.

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 is relatively simple with 4 parameters and no output schema. The description provides the essential context: admin requirement, naming convention through an example, and relationship to role assignment. It adequately equips an agent to invoke the tool correctly, though it omits details like validation or duplicate behavior, which are less critical for a basic create 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%, so the description must compensate. The example thoroughly explains the three required parameters (name, resource, action) by showing a concrete instance. However, the optional 'description' parameter is not mentioned, leaving its purpose unexplained. This partial compensation justifies a mid-range score.

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: 'Create a new usermanagement permission' with a specific verb and resource. The example (name='dataset.export', resource='dataset', action='export') further clarifies the exact nature. This distinguishes it from sibling tools like create_role or grant_role_capability by focusing on permission objects.

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 context of use: it is an admin action, and it explicitly notes that attaching the permission to roles is done via a separate 'role-permissions API'. This implies the tool is only for creation, providing workflow context and setting boundaries without naming alternatives explicitly.

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 burden of behavioral disclosure. It adds context by noting the admin requirement and that the role must be assigned after creation, but it does not mention side effects, idempotency, or permission requirements beyond the 'Admin' tag.

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, front-loaded sentence that efficiently states the action, provides an example, and links to the next step without any 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 simple create tool with a fairly self-explanatory schema, the description covers the basic action and next step. However, it omits details about the response, how to verify the role was created, or interactions with related tools like brainkb_available_roles, leaving some context gaps.

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

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

The schema has no descriptions (0% coverage) and the description does not explain the parameters. The example 'External' hints at the 'name' parameter, but nothing is said about 'category' or 'description', leaving them semantically underspecified.

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 role/group, using the specific verb 'Create' and resource 'role/group'. It also distinguishes the action from assignment by referencing brainkb_assign_role as the follow-up step, which separates it from sibling tools like assign_role.

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 indicates this is an admin-only operation and that the created role is meant to be assigned later via brainkb_assign_role, providing a clear usage context. It does not explicitly exclude alternatives like create_permission, but the flow is clear enough for a simple create-then-assign pattern.

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

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

With no annotations, the description fully carries the transparency burden: it discloses global slug uniqueness, 409 conflict behavior, slugs never being reused/deleted, visibility enum values, description surfacing in the registry, and owner designation. This is exceptional behavioral disclosure 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?

Compact and well-structured with labeled parameter descriptions. Every sentence carries information; purpose is front-loaded and there is no filler.

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

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

Covers most operational aspects for a creation tool: ownership, uniqueness, role requirements, and parameter semantics. Missing the 'name' parameter and return value details, but the absence of an output schema makes return-value disclosure less critical.

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 slug format/constraints, visibility allowed values, description purpose, and space_type semantics — all adding meaning beyond the bare string types in the schema. However, it omits the required 'name' parameter entirely, leaving its meaning to inference.

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 'Create a workspace/space' — a specific verb and resource — and immediately clarifies ownership ('caller becomes owner'), distinguishing it as the space-creation tool 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?

Provides clear role-based context for when to use space_type 'individual' versus 'team' (any write-capable role vs Admin/SuperAdmin or granted permission). It implies the tool's use for creation but does not explicitly name alternatives or when-not-to-use 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 provided, the description carries the full burden and excels: it discloses that the token is shown ONCE and never again, instructs to copy it and set as BRAINKB_TOKEN, warns to treat it like a password, and notes server-capped expiration. These are critical behavioral traits beyond the basic creation 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 four sentences, each earning its place: action, prerequisite, security warning, and parameter semantics. It is front-loaded with the core purpose and contains 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?

For a simple two-param tool with no output schema, the description is complete. It implies the return value ('the returned token'), covers the entire lifecycle (creation, storage, reuse, expiry), and includes security guidance, leaving no important gaps for the 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?

Schema description coverage is 0%, but the description compensates fully by explaining `name` as a label with an example ('laptop') and `days` as lifetime with a default (90) and server-capped limit. This adds meaning well beyond the bare schema properties.

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 action ('Generate a Personal Access Token (PAT)') and its purpose ('for browser-free auth'). This distinguishes it from sibling tools like brainkb_login and brainkb_use_token, making the tool's role 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?

It explicitly provides a prerequisite ('Requires you to be logged in already (brainkb_login or brainkb_globus_login)') and describes the post-condition ('no login or browser is needed until it expires'). This gives clear when-to-use context within the authentication flow, though it doesn't mention alternatives like brainkb_use_token, the guidance is specific and actionable.

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 does disclose an authorization requirement ('Admin'), but does not elaborate on side effects such as reversibility, session invalidation, or impacts on user data. This is a minimal but present disclosure for a mutation 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 entire description is a single, front-loaded sentence that wastes no words. It immediately states the admin scope, action, and parameter usage.

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 one-parameter tool with no output schema and no annotations, the description provides the core purpose, authorization level, and parameter role. It doesn't cover success/failure responses, but that's not critical for such a straightforward action.

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 lists only 'email' with no description (0% coverage). The description clarifies that email is the identifier used to locate the account for deactivation, adding essential meaning beyond the bare schema. It could be more specific about the expected email format, but it is adequate for a single 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 uses a specific verb 'deactivate' tied to a clear resource ('user's account') and identifies the lookup method ('by email'). This clearly distinguishes it from sibling tools like brainkb_activate_user, brainkb_ban_user, and brainkb_unban_user.

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

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

The '(Admin)' prefix signals that this tool is restricted to admin users, giving some usage context. However, it neither explicitly states when to use this tool over alternatives nor provides exclusion criteria for when not to use it. Usage is implied by the action name rather than explicitly guided.

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 the output is JSON-LD and represents the job's added triples, which implies a read-only operation. However, it does not mention error behavior, authentication requirements, or what happens for invalid/nonexistent job IDs. The behavioral disclosure is minimal but not misleading.

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

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

A single, concise sentence that is front-loaded with the core purpose. Every word adds value, and there is no extraneous information.

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

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

For a simple one-parameter read operation, the description covers the essential function and output format. However, it lacks usage guidance and does not explain how this relates to its sibling delta tools, which slightly reduces completeness in a broader context. Still, the low complexity makes the description largely adequate.

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

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

The schema has 0% description coverage for the single 'job_id' parameter, and the description does not elaborate on it. The name 'job_id' is somewhat self-explanatory, and the phrase 'a job' offers indirect context, but the description fails to explicitly define the expected format or semantics, leaving the agent to guess.

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 returns the exact triples a job added, formatted as JSON-LD. It is specific about both the resource (a job's delta) and the output format, and it distinguishes itself from sibling tools like brainkb_delta_compare and brainkb_delta_history by emphasizing 'exact triples'.

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 the raw set of triples added by a job. However, it does not explicitly state when to prefer this over alternatives like brainkb_delta_history or brainkb_delta_compare, nor does it provide any exclusions or prerequisite context.

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 describes what the tool returns (counts and triples for A-only, B-only, and shared categories), which is a key behavioral aspect. However, it does not explicitly state whether the operation is read-only or mention any side effects, though the act of comparing implies no mutation.

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 concise sentence that front-loads the action and resource, followed by a colon and a compact list of output categories. Every word contributes value with 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 simple tool with only two string parameters and no output schema, the description adequately covers the essential return values (counts and triples for each category). It does not discuss edge cases like identical jobs or whether triples are full URIs, but the core functionality is well communicated for a tool of this complexity.

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 description coverage, the description must compensate. It does so by mapping the two parameters (job_id_a and job_id_b) to the 'A' and 'B' in 'A-only / B-only', giving semantic meaning to the parameter order. It lacks details about ID formats or job definitions, but the mapping is sufficiently clear for a simple two-parameter tool.

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: comparing two jobs' deltas and reporting A-only, B-only, and shared triple counts plus triples. The verb 'compare' and specific resource 'two jobs' deltas' make the purpose unambiguous and distinguish it from sibling tools like brainkb_delta that may compare a single job to a base.

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 does not provide any guidance on when to use this tool versus the sibling tools brainkb_delta or brainkb_delta_history. There is no mention of conditions, prerequisites, or exclusions, leaving the agent without context for tool selection beyond the inherent meaning of 'compare two jobs.'

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 burden of behavioral disclosure. It explains that the result contains one entry per ingest delta, lists the included fields (job, triple count, timestamp), and states the ordering is newest first. This gives a clear picture of what the tool returns, though it does not mention authentication or error behavior.

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

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

The description is a single, front-loaded sentence that efficiently communicates the resource, the nature of the entries, and the ordering. Every word contributes value, and there is no wasted 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?

For a simple read-only history tool with one parameter and no output schema, the description supplies sufficient contextual detail: what each entry contains and the sort order. It stops short of specifying the exact return envelope or pagination, but these are not strictly necessary for basic use.

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 only one required parameter, named_graph_iri, with no description. The tool description indirectly clarifies this parameter by stating the tool operates on 'a named graph', so the meaning of the parameter is inferable. However, it does not explain IRI format or constraints, and at 0% schema coverage more explicit compensation would be beneficial.

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's function: returning change history for a named graph, with one entry per ingest delta. It specifies the entry contents and ordering, making it distinct from other history/provenance tools, though it lacks an explicit verb.

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 the tool is for inspecting the ingest delta history of a named graph, but it does not explicitly state when to choose this over siblings like brainkb_delta_compare or brainkb_provenance_graph. There is no exclusion or alternative guidance.

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

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

With no annotations, the description carries the full burden. It discloses that the upload will not be ingested, which is a useful behavioral trait. However, it does not state whether the deletion is irreversible, what happens to the underlying stored data, or any permission requirements, leaving gaps in 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 a single, front-loaded sentence with no wasted words. Every word contributes to the meaning, and the structure is perfectly concise for the operation.

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 one-parameter delete tool, the description covers the core action and the key distinction (not ingesting). It lacks context on how to find the upload_id and any side effects, but given the inherent simplicity and lack of output schema, the description is mostly 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 description coverage is 0%, so the description must compensate. The only parameter, upload_id, is not explained beyond the obvious; the description says 'staged uploads' but does not clarify how to obtain or identify the ID. The description adds minimal semantic value over the schema's name/type.

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 ('Delete') and resource ('one of your staged uploads'), clearly distinguishing it from siblings like brainkb_ingest_upload (which would consume the upload) and brainkb_list_uploads (which only lists). The scope is unambiguously defined.

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 the use case (when you want to remove a staged upload without ingesting it) but does not explicitly mention alternatives or exclusions. It does not reference related tools like brainkb_list_uploads to obtain the upload_id, leaving some usage context implicit.

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 key behavioral traits: the code is single-use, never echoed back, and is exchanged for a session token. This adds useful context beyond the schema, though it doesn't mention error behavior or subsequent token storage.

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 two short sentences, front-loaded with the main action, and contains no filler. Every word adds value.

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 login flow and code handling clearly. An output schema exists, so return values need not be described. The only gap is the unexplained base_url parameter and edge-case handling, but for a simple login-completion tool, this is 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 gives meaning to the 'code' parameter by explaining it as a one-time browser-displayed code, but it does not mention the optional 'base_url' parameter. Since schema description coverage is 0%, the description should compensate for all parameters; it only partially does.

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 completes an OAuth login by exchanging a one-time code for a session token, explicitly referencing the initiating sibling tool brainkb_globus_login. This distinguishes it from other authentication tools in the sibling list.

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

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

The description explicitly says the login was started with brainkb_globus_login, making the prerequisite and flow clear. It doesn't list alternatives or exclusions, but the reference to the initiating tool provides strong contextual guidance for when to use this tool.

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 explains that the tool returns a URL for browser opening, requires interactive consent, and produces a one-time code. This is valuable context, though it omits potential error conditions or expiration 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 concise and front-loaded: it states the action, gives the usage alternative, and describes the follow-up step in three sentences. Every sentence adds unique value without redundancy.

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

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

The description covers purpose, usage context, return value (URL), and the necessary next step (finish_login). Given that an output schema exists, detailed return formatting is unnecessary. However, it lacks error scenarios and full parameter explanation, preventing 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?

Schema coverage is 0%, so the description must compensate. It names the provider options (Globus/ORCID/GitHub) which informs the 'provider' parameter, but it does not mention 'base_url' at all. Thus it partially clarifies parameters but leaves a 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 starts with 'Start an OAuth login' which is a specific verb+resource, clearly distinguishing this tool from the password-based brainkb_login. It also mentions the supported providers (Globus / ORCID / GitHub), making its scope explicit.

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 instructs to use this tool instead of brainkb_login when the user signs in with Globus, and directs the user to pass the one-time code to brainkb_finish_login. This provides clear when-to-use and next-step guidance, exceeding typical descriptions.

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 present, so the description carries full behavioral burden. It adds critical auth context ('Admin only'), enumerates valid capabilities, and explicitly excludes forbidden ones. This goes beyond the schema. It lacks details on side effects (e.g., idempotency, whether existing grants are replaced) but the auth and capability constraints are valuable.

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

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

Two sentences, front-loaded with 'Admin only' and the core action. The examples and the grantable list are concise and necessary for correct invocation. No filler.

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

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

For a two-parameter tool with no output schema and no annotations, the description is reasonably complete. It provides purpose, auth requirement, valid values, and exclusions. It omits error handling or return behavior, but these are not essential for such a simple grant operation. The absence of member format detail is a minor gap.

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

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

Schema coverage is 0%, so the description must compensate. It richly clarifies the 'capability' parameter by listing valid values and examples. However, the 'member' parameter is only described indirectly as 'to a user', without specifying expected format (username, email, user ID). This partial compensation gives a middling score.

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: 'Delegate a capability to a user' and provides concrete examples ('create_team_space', 'manage_team_space') and a full list of grantable capabilities. It distinguishes from sibling tools like brainkb_grant_role_capability by emphasizing the target is a user, and the admin-only restriction further clarifies scope.

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

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

The description explicitly marks the tool as admin-only and lists allowable capabilities, including an explicit exclusion of admin-only capabilities ('NOT the admin-only grant/sparql_admin'). It does not explicitly name alternative tools for role-level grants, but the user focus and capability list make the intended use clear. Missing explicit 'when not to use' via alternative tool names, but partial exclusion is present.

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 admin-only auth, group-wide effect (EVERY member), prerequisite (create group first), and capability restrictions. While it does not mention reversibility or return value, the core behavioral traits are sufficiently covered.

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 purpose. It uses an em-dash for the example and includes necessary exclusions and workflow without redundancy. Every sentence contributes value.

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 only two simple parameters and no output schema, the description covers purpose, authorization, prerequisites, and valid inputs. It is complete enough for an agent to select and invoke 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?

Schema description coverage is 0%, but the description fully compensates. It defines 'capability' as one of the listed grantable capabilities and clarifies that 'role' is a group created via brainkb_create_role. Examples provide concrete expected values, making the parameters unambiguous despite lack of enums.

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 'Grant a capability to a whole role/group' and its effect 'so EVERY member gets it'. It provides concrete examples (e.g., 'uk_collaborator' with 'ingest') and distinguishes from sibling tools like brainkb_grant_capability by emphasizing the role/group scope and from brainkb_revoke_role_capability by the grant verb.

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 specifies the admin-only requirement, lists grantable capabilities explicitly (create_private_space, create_team_space, etc.) and exclusions (NOT 'grant'/'sparql_admin'). It also gives a workflow: create the group first with brainkb_create_role, then assign users with brainkb_assign_role, providing clear when-to-use context and alternatives.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the operation runs in the background, returns a job_id, and requires polling via brainkb_job_status. This is valuable behavioral information beyond the basic 'ingest' verb, though it does not mention potential side effects or prerequisites.

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 two sentences long and immediately states the tool's purpose. Every part adds value: the action, the formats, the target, and the follow-up polling step. 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?

The tool has 3 parameters, no output schema, and no annotations. The description adequately covers the core workflow: what to provide (files, graph) and what to expect (job_id, background execution, polling). It does not detail max_concurrency or job status semantics, but for a relatively straightforward ingest tool, it is 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?

Schema description coverage is 0%, so the description must compensate. It clarifies that file_paths are local RDF files with specific formats and that named_graph_iri is the target graph. However, max_concurrency is not mentioned at all, leaving its purpose (parallelism control) implied only by its name and default value.

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 ('Ingest local RDF files') and the target resource ('into a named graph'). It lists supported formats, which adds specificity, and the phrasing distinguishes it from sibling tools like brainkb_ingest_text by focusing on files.

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 how to use the tool: it mentions local RDF files, a named graph, and explicitly instructs to poll with brainkb_job_status after receiving a job_id. It does not explicitly state when not to use it or name alternatives, but the usage context is clear.

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

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

With no annotations, the description excels at disclosing behavior: background execution with job_id, append-only semantics, permanence of mangled data, and the risk of silent corruption through string context. It also explains the integrity contract and clean rejection on mismatch, providing exceptional 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 dense but every sentence adds critical information: purpose, return value, prerequisites, integrity contract, and hazards. It is well-structured, starting with the core action, then contextual details, and is appropriately sized for the tool's complexity.

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

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

Despite no output schema or annotations, the description covers purpose, return value, job polling, prerequisites, append-only behavior, integrity checks, and parameter guidance. It references related tools and would allow an agent to invoke this tool safely and effectively.

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 has 0% description coverage, but the description richly explains the semantics of sha256 and expected_bytes as an integrity contract, warns about data as a string, and implies named_graph_iri via 'named graph' and registration. This fully compensates for the schema's lack of 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 ingests raw RDF text (Turtle/N-Triples/JSON-LD) into a named graph, with specific verb and resource. It distinguishes itself from sibling tools like brainkb_ingest_files and brainkb_ingest_upload by focusing on text input and highlighting background processing.

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

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

Provides clear context: prerequisites (registered graph, write access), how to track progress (poll brainkb_job_status), and when to use integrity params (when RDF came from a file). Does not explicitly name alternative tools for file/upload ingestion, but the tool name and 'raw RDF text' make the distinction evident.

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

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

With no annotations, the description fully carries the behavioral disclosure burden. It transparently explains the internal server flow (server reads its own staged copy and posts to the ingest API), side effects (staged copy is deleted once accepted), and the risk of splitting (silently detaches triples). It also informs the user about the returned upload_id and sha256 for verification, as well as the need to poll job status. This level of detail exceeds 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 thorough but lengthy, containing a full Python code example and repeated emphasis on the 'library reads the file' point. While every sentence provides some value, the structure could be tightened; the code example is somewhat long and the core message is repeated across the first and third paragraphs. It is not as crisp as it could be, but it is not unstructured.

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 the absence of both annotations and an output schema, the description covers the full lifecycle: staging, ingestion, return value (job_id), follow-up actions (poll brainkb_job_status, reconcile with brainkb_delta), and cleanup (staged copy deletion). This provides the agent with a complete operational picture.

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 no descriptions for the two parameters, and the description compensates by explaining that upload_id comes from the staging step and that the named_graph_iri is the target graph. It provides a concrete example of how upload_id is obtained and implies its format (up_...). However, it does not explicitly define the syntax or constraints for named_graph_iri, so it's not a full 5, but it adds meaningful semantic context.

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, actionable statement: 'Ingest a file you staged with `POST /upload` into a named graph.' This clearly identifies the tool's function (ingesting a staged file), the resource (named graph), and the mechanism (using an upload_id). It also distinguishes itself from sibling tools like brainkb_ingest_text and brainkb_ingest_files by explicitly scoping to large local files staged via upload.

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 strong contextual guidance: 'This is the route for a large local file' and explains that the RDF never passes through a model's context, so there's no context-window ceiling. It also warns against splitting documents because it 'breaks blank-node identity'. However, it does not explicitly name alternative tools or state when not to use this tool beyond the large-file scenario, so it falls 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?

No annotations are present, so the description carries the burden of behavioral disclosure. It adds useful context by detailing the returned fields and the conditional 'when complete' summary. However, it does not explicitly state that the operation is read-only, nor does it address error behavior, authentication, or rate limits, leaving some transparency gaps.

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 sentence, front-loaded with the core purpose and followed by a concise list of output components. Every phrase is informative; there is no redundancy or filler.

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

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

For a simple one-parameter status tool, the description covers the key output content well, including the condition for a summary. It does not mention how to discover job_id (e.g., via brainkb_list_jobs) or error handling, but given the simplicity and lack of output schema, the description 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 schema only defines job_id, and the description adds that it concerns an 'ingest job', implying job_id is the identifier for that job. Still, with 0% schema coverage, the description does not fully compensate: it does not explain how to obtain job_id or provide formatting nuances, so semantic support is minimal.

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's purpose: reporting detailed status of a single ingest job. It lists specific output elements (status, progress %, current file/stage, per-file failures, summary), which distinguishes it from sibling tools like brainkb_list_jobs (plural, listing all jobs) and brainkb_recover_job (recovery 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 scope is made clear ('one ingest job') indicating use when a specific job ID is known and detailed status is needed. It does not explicitly mention alternatives or when-not to use, but the singular focus differentiates it from list-oriented or recovery tools without ambiguity.

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 of behavioral disclosure. It indicates a read-only 'List' operation, which is a positive signal. However, it does not disclose any additional behavioral traits such as permission requirements, output format, or that it does not modify anything. The description adds minimal context beyond the obvious.

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 sentence. It is front-loaded with the action 'List' and immediately specifies the resource and scope. There is no wasted text.

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 one-parameter tool with no output schema, the description provides adequate context: it names the resource and gives a parenthetical clarification of what the access rules are. However, it does not mention output format or any side effects, but given the simplicity, it is nearly complete. Missing details like explicit return structure would push it lower.

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% and the slug parameter has no description. The description adds semantic meaning by implying that slug identifies the space whose rules are listed ('a space's fine-grained access rules'). However, this is indirect rather than explicitly stating 'slug is the space slug.' The description partially compensates for the schema gap 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 a specific verb and resource: 'List a space's fine-grained access rules.' It also clarifies the rules are about member/manager status, which distinguishes it from unrelated list tools. The purpose is not a tautology and directly reflects 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 implies usage context: you use this tool to list access rules for a space. However, it does not explicitly mention when to use this versus alternatives (e.g., brainkb_add_access_rule, brainkb_remove_access_rule), nor does it provide exclusions or prerequisites. The guidance is only implied.

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 mentions '(Admin only)' as a key prerequisite and describes the tool as a 'catalog', implying a read-only operation. However, it does not explicitly state that it does not modify data or describe any return format, which would add further 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 at two sentences, with the admin-only restriction front-loaded. Every sentence adds value: the first defines the content and scope, the second gives a usage scenario. There is no redundancy or 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?

This is a simple zero-parameter catalog tool with no output schema or annotations. The description covers the purpose, content, and when to use it, which is sufficient for basic understanding. It does not describe the exact return structure, but for a simple list operation the information provided is adequate.

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

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

The tool has zero parameters, and the schema description coverage is 100%, so the baseline for parameter semantics is 4. The description adds no parameter-specific information, but none is needed since there are no parameters to clarify.

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 catalogs all KG capabilities, specifying that it includes grantability status, admin-only status, and descriptions. It uses a specific verb ('Catalog') and identifies the resource. However, it does not explicitly distinguish from the sibling tool 'brainkb_capabilities', which appears to be closely related.

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 a clear use case: 'Use this to see the available permission options before granting to a user or group/role.' This gives an explicit when-to-use instruction. It does not mention alternatives or when not to use it, so it falls 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does add useful context: the tool returns jobs in reverse chronological order ('newest first') and includes status and progress fields. However, it omits other behavioral details such as authorization requirements, pagination behavior, and how the limit parameter affects results. The description is not misleading, but it is minimal.

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, concise sentence that immediately communicates the action, target, and key details. Every word contributes to understanding the tool's purpose. There is no fluff or unnecessary information.

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

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

For a simple listing tool with one optional parameter and no output schema, the description covers the core functionality but leaves gaps. It mentions the output includes status and progress but does not describe the full response structure or how the limit parameter works. Since no output schema exists, the description should provide more detail about the return format, but it is adequate for a basic understanding.

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 one parameter (limit) with a default of 50, but the description does not mention it at all. Schema description coverage is 0%, so the description was expected to compensate, but it fails to explain what 'limit' means or how it affects the output. The parameter is simple, but the description adds zero value beyond the schema itself.

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: listing the user's ingest jobs, with specific details on ordering (newest first) and included information (status and progress). It distinguishes itself from sibling tools like brainkb_job_status (which likely targets a single job) by explicitly saying 'jobs' and specifying 'ingest jobs'.

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 the use case (listing ingest jobs) but gives no explicit guidance on when to use this tool versus alternatives like brainkb_job_status. It doesn't mention exclusions, prerequisites, or when a different tool would be more appropriate. The context is clear but not fully articulated.

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 notes '(Admin)' as an access constraint and clarifies the scope (usermanagement vs KG capabilities). It implies read-only behavior via 'List', but does not explicitly state side-effect-free operation. With no annotations, the description provides adequate behavioral insight.

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

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

Two concise sentences, front-loaded with the action and resource, and no wasted words.

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

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

Covers the essential context: admin requirement, what the list contains, and the distinction from capabilities. For a zero-param list tool without output schema, this is 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?

With zero parameters and 100% schema coverage, the description needs no parameter explanation. The baseline applies.

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

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

The description uses a specific verb 'List' and identifies the resource 'all usermanagement permissions', explaining them as resource/action pairs. It explicitly differentiates from sibling tool brainkb_list_capabilities, making its purpose unmistakable.

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 mentions that KG action-capabilities are listed by brainkb_list_capabilities, offering an explicit alternative and clarifying when not to use this tool. It lacks more general when-to-use context, but for a simple list tool this is sufficient.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a key behavior: inaccessible private-space graphs are hidden from the results, indicating caller-aware filtering. This goes beyond the basic list action and is useful for understanding the tool's output.

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-constructed sentence with a parenthetical clarification. It is front-loaded and every word adds meaning, with no redundancy or fluff. Ideal conciseness for the tool's simplicity.

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 0-param, no-output-schema list tool, the description is complete. It states what is listed, the filter behavior, and implies the return value (the list of graphs). No additional details are necessary for the agent to use this tool effectively.

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 has zero parameters and 100% coverage, and the 0-param baseline is 4. The description does not need to elaborate on parameters since there are none, and it correctly focuses on the tool's purpose and 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 clearly states the action (List) and the resource (registered named graphs), and it includes a specific scope qualifier: visible to the caller, with private-space graphs hidden. This distinguishes it from sibling list tools like brainkb_list_spaces or brainkb_list_users.

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 when to use this tool (to discover graphs the caller can access) but does not explicitly state alternatives or exclusions. The visibility qualifier gives some contextual guidance, but there is no explicit 'use this instead of X' or conditions for 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 fully carries the burden. It thoroughly explains the meaning of each returned permission field (your_role, is_owner, access, can_write) and clarifies that can_write alone doesn't guarantee ingest capability. This is rich behavioral context beyond a simple listing.

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

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

The description is well-organized with a clear opening sentence and bullet points for each field. Every sentence adds value, and the structure makes the permission semantics easily scannable. There is no wasted text.

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 zero-parameter simplicity, the description is complete. It explains what the tool returns and how to interpret the annotations, which is essential since there is no output schema. It also provides relevant caveats about the 'ingest' capability, making the tool's usage fully understandable.

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

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

The tool has zero parameters, and the schema is empty. Per the rubric, a baseline of 4 applies, and the description correctly focuses on the output semantics instead. No parameter explanation is needed.

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 lists spaces the user can see, distinguishing it from other space-related tools like reading a space's contents or creating a space. It specifies the scope (own/member/public) and the permission annotations, making the 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 provides a clear usage context: 'Use this to tell the user which spaces they can read vs. write vs. only see as public.' It gives a concrete use case but does not explicitly name alternatives or exclusion conditions, which is acceptable for a straightforward listing tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the secret is never shown and lists the exact metadata fields returned, including status indicators (active/revoked/expired). This goes beyond minimal disclosure and sets accurate expectations for a read-only list 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 two sentences, each earning its place. The first sentence concisely lists the included metadata fields, and the second sentence provides a practical cross-reference to the revoke tool. There is zero fluff, making it highly 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?

For a zero-parameter list tool, the description fully covers what the agent needs to know: it lists tokens, returns metadata only (including status), and never exposes the secret. The cross-reference to brainkb_revoke_token completes the context for typical usage. No output schema exists, but the description sufficiently specifies the return content.

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

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

The tool has zero parameters and the input schema is empty, so the baseline for parameter semantics is 4. The description adds no parameter details (as there are none), but it does explain the output structure and the usefulness of the 'id' field, which indirectly communicates semantics for downstream use.

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 ('List') with a clear resource ('Personal Access Tokens') and enumerates the returned fields (id, name, prefix, timestamps, status). It distinguishes from sibling tools like brainkb_create_token, brainkb_use_token, and brainkb_revoke_token by focusing solely on listing metadata.

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 tells the user to use the returned 'id' with brainkb_revoke_token, providing a direct usage hint. It does not explicitly state when not to use it, but the mention of metadata-only and the secret never shown makes its scope clear, differentiating it from token creation or usage tools.

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

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

No annotations are provided, so the description carries the full burden. It discloses the scope (own uploads only) and the displayed fields, but does not explicitly state that the operation is read-only or mention any side effects, rate limits, or authentication requirements. The verb 'List' implies a read operation, but the description could be more explicit about safety.

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 two sentences, front-loaded with the main purpose, and each sentence adds useful information without waste.

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 adequately explains what the user will see (upload_id, size, sha256, expiry). It also clarifies the scope and the 'not yet ingested' condition, which is sufficient for a simple list tool.

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

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

There are no parameters, so the schema covers everything. The description correctly focuses on the fixed behavior of the tool, earning the baseline 4 for zero-parameter tools.

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 lists RDF files the user has staged via POST /upload but not yet ingested. It specifies the scope ('Only your own uploads are visible') and distinguishes from sibling tools like ingest_upload and discard_upload.

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: the tool is for viewing staged uploads that have not been ingested. It implies when to use it (when you need to see your pending uploads) but does not explicitly mention alternatives or when not to use it, though sibling names like upload_status suggest related purposes.

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 discloses the admin requirement and the output fields (profile_id, email, roles, providers, ban status). However, it lacks details on pagination, limit behavior, and exact matching semantics of q/role, and the 'or' in 'filter by q or role' is ambiguous.

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 two sentences, front-loaded with the action, and every clause adds value. It avoids repetition of schema content and is efficient for an agent to parse.

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 list tool with no output schema and no annotations, the description covers the essential aspects: purpose, filters, and output fields. It omits pagination and limit defaults, but these are minor for a read-only listing tool. Overall, it is sufficiently 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 description coverage is 0%, so the description must compensate. It explains q as 'name/email/orcid' and role as a filter, adding value beyond the schema. However, it fails to mention the limit parameter, which is only self-evident from its name and default in the schema. Partial compensation leaves a 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: 'List users (profiles)' with a specific resource and context. It distinguishes from sibling list tools by naming the object type and specifying filter options (q, role), 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 '(Admin)' prefix indicates restricted usage context. The description implies when to use it (admin user listing with filters) but does not explicitly name alternatives or provide when-not-to-use guidance. The context is clear enough for an agent to select it among sibling list tools.

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

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

With no annotations, the description carries the full burden and excels: it discloses that the JWT is cached per-session and isolated per caller, that passwords/tokens are never echoed, that SSO mints a refresh token exchanged for per-service tokens, and that a legacy fallback exists when SSO is unavailable. This provides substantial behavioral insight without contradicting any structured data.

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 compact paragraph with a clear front-loaded purpose and every sentence adding detail on SSO, fallback, or usage alternatives. It is slightly longer than strictly necessary but each sentence serves a purpose, making it well-structured for the tool's complexity.

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

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

Given the tool's complexity (SSO, fallback, session caching), the description is remarkably complete. It covers key behaviors, edge cases (no SSO, hosted remote), and security details. An output schema exists, so return values are properly delegated, and the description provides all other necessary context for an agent to use the tool safely and effectively.

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

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

The schema has 0% description coverage for parameters. The description adds meaning to email and password via 'user's credentials,' but it does not explain base_url at all, leaving a significant gap for that parameter. The description focuses on behavior rather than parameter roles, so it only partially compensates for the lack of 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's purpose: 'Authenticate to BrainKB with the user's credentials' – a specific verb and resource. It also differentiates from siblings like globus_login and use_token by describing its credential-based SSO mechanism and session caching.

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 on when to use the tool, including an explicit alternative for hosted remote environments: 'On the hosted multi-user remote you can skip this and instead have your client send an Authorization: Bearer <token> header.' It mentions fallback behavior but does not explicitly exclude other auth tools like finish_login or globus_login.

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 it discloses key behavioral context: it clears the cached token for the current session, implying it is local to the session and does not revoke the token server-side. This is important beyond just saying 'logout'.

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 sentence that is front-loaded with the action and resource, with no wasted words.

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 no-parameter tool with an output schema, the description completely conveys the tool's purpose and effect. It doesn't need to explain return values thanks to the output schema, and sibling context is not necessary for this straightforward 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 tool has zero parameters, so the schema already fully covers parameters. The baseline is 4 for no-parameter tools, and the description adds nothing to parameter semantics, which 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 uses a specific verb ('Forget') and resource ('cached token for this session'), clearly distinguishing this session-local logout from sibling tools like brainkb_revoke_token which permanently revokes a 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 provides no guidance on when to use this tool versus alternatives such as brainkb_revoke_token or brainkb_use_token. It only states what it does, not the context or exclusions.

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 explaining side effects and requirements. It does not state whether this is a read-only operation, whether authentication or permissions are needed, or any error/rate-limit behavior. The only extra context is the output format (JSON-LD), which is minimal.

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, concise sentence that leads with the key concept (PROV-O history) and includes the output format. Every word adds value, and there is no wasted text.

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 tool with one parameter and no output schema, the description is nearly adequate. It conveys the purpose and output format, but lacks crucial context about return structure, error conditions, or how this differs from related provenance/delta tools. A richer description would improve usability.

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 provides 0% description coverage, so the description must clarify the parameter. It does link the 'named graph' phrase to the required named_graph_iri, indicating the parameter identifies the target graph. However, it does not specify IRI format requirements or provide examples, so the added value is limited.

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 the resource ('PROV-O ingestion/activity history for a named graph') and mentions the output format (JSON-LD), but lacks an explicit verb like 'get' or 'retrieve'. It does not clearly differentiate from sibling tools like brainkb_provenance_job or brainkb_delta_history, making the tool's exact action somewhat ambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives. The description only states what it returns, not in what scenarios it is appropriate or preferable to sibling tools such as brainkb_provenance_job or brainkb_delta_history.

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. It discloses output format (JSON-LD) and scope (one ingest job), but does not explicitly state read-only semantics, error handling, or rate limits. Provides some behavioral context but leaves important details implicit.

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

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

A single sentence with no filler, front-loading the key information. It is appropriately brief for a simple one-parameter tool, though it omits useful context that could be included without losing conciseness.

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 too sparse for an agent to use confidently. It does not clarify how this relates to brainkb_provenance_graph, what the JSON-LD bundle contains, or whether the job must be in a specific state. Missing usage guidance and parameter explanation leave significant gaps.

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

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

Schema coverage is 0%, so the description must compensate. It mentions 'one ingest job' but does not explain what job_id is, how to obtain it, or format constraints. The description adds minimal semantic value beyond the bare schema field.

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 the resource (PROV-O provenance bundle in JSON-LD) and scopes it to a single ingest job, distinguishing it from brainkb_provenance_graph. However, it lacks an explicit verb like 'retrieve' or 'get,' making the action implicit.

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

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

No guidance is provided on when to use this tool versus alternatives like brainkb_provenance_graph or brainkb_job_status. It does not state prerequisites, exclusions, or the context in which this tool is preferred.

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 bears the transparency burden. It discloses that read access depends on space visibility (public vs private), which is valuable behavioral context. It does not mention potential large payloads for spaces with many graphs, nor confirm absolutely no side effects beyond the 'read' verb.

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

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

Two compact sentences convey purpose and access requirements without redundancy. Every word earns its place; the description is front-loaded with the primary action.

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 simplicity (one parameter, simple read operation), the description covers the essential purpose and access constraints. Minor gaps remain in specifying the exact response envelope (e.g., raw JSON-LD vs wrapped) and error conditions when the slug is invalid or access is denied.

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 one required parameter, 'slug', with no description (0% coverage). The description mentions 'a space's graphs' but never explains that 'slug' is the space identifier or the expected value format, leaving the agent to infer the semantics.

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

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

The description explicitly states the tool reads all RDF (JSON-LD) in a space's graphs, specifying both the verb (read) and the resource (all RDF in space graphs). This distinguishes it from sibling tools like brainkb_sparql (query) and brainkb_search (search).

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 public spaces are readable by anyone while private spaces require membership, providing access context. However, it does not explicitly contrast this tool with alternatives like brainkb_sparql for querying or brainkb_delta for examining changes, leaving the usage boundaries implied.

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 must carry the burden of disclosing behaviors. It does mention that the tool 'marks it recoverable/errored', which is a meaningful state-change disclosure. However, it does not clarify whether this is a destructive or reversible operation, what conditions are required (e.g., job must exist), or what happens on failure, 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 a single sentence, 14 words, front-loaded with the core action and augmented with a clarifying parenthetical. Every word earns its place; there is no redundancy or unnecessary detail.

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 one required parameter and no output schema, the description covers the essential purpose and a key side effect. However, it does not explain the return value, error behavior, or prerequisites (e.g., the job must be in an ingest pipeline), leaving modest gaps that could confuse an agent on first use.

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 provides only a 'job_id' string with no description, and the tool description does not explicitly explain the parameter. However, the phrase 'stuck/errored ingest job' implies that job_id identifies such a job, and the parameter name is self-explanatory. This adds marginal meaning beyond the schema but does not cover format requirements or how to obtain the ID.

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: 'Attempt to recover a stuck/errored ingest job'. It specifies a concrete verb ('recover'), a target resource ('ingest job'), and a condition ('stuck/errored'), distinguishing it from all sibling tools that focus on listing, creating, or managing jobs, not recovery. The parenthetical 'marks it recoverable/errored' adds a clear side effect, making the 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 implicitly provides usage context by specifying the tool is for 'stuck/errored' ingest jobs, which tells the agent when to invoke it. However, it does not explicitly state when not to use it (e.g., do not use for active jobs) or mention alternative tools like list_jobs or job_status, so it stops short of being a full 5.

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

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

With no annotations provided, the description is the only source of behavioral information. It clearly indicates a destructive delete operation and hints at a permission role via '(Space manager)', but it does not disclose reversibility, side effects, or detailed permission requirements.

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

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

The description is a single, front-loaded sentence that states the action and resource, plus a brief cross-reference to list_access_rules. It is remarkably concise and every word contributes to understanding, with 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?

For a destructive tool with two required parameters and no output schema, the description is too sparse. It references the list tool for finding IDs but does not explain the need for slug, the consequences of deletion, or any context around space management. Significant gaps remain for an agent to safely invoke this 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 has two required parameters but 0% description coverage. The description only references 'by its id', which aligns with rule_id, but leaves slug completely unexplained. It fails to clarify the role of the slug parameter or how the parameters interact, so the description does not compensate for the schema's lack of detail.

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 'Delete' and a clear resource 'fine-grained access rule', with the identifier method 'by its id'. It distinguishes itself from sibling tools like brainkb_add_access_rule and brainkb_list_access_rules by referencing the latter, making its role unmistakable.

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 clearly implies when to use this tool: when you need to remove an access rule. It points to brainkb_list_access_rules as a prerequisite for finding the rule ID, providing useful context. However, it does not explicitly state exclusions or alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the operation is admin-scoped but does not mention whether removal is reversible, what happens if the email or role is invalid, or whether the operation is idempotent.

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 sentence and front-loads the verb and object. Every word contributes meaning, with 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 simple two-parameter removal tool, the description provides the essential action and actor, but it omits behavioral details like idempotency or error conditions. The lack of annotations and output schema makes this minimally sufficient but not 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?

Schema description coverage is 0%, so the description must compensate. It implicitly identifies 'email' as the user identifier and 'role' as the role/group being removed, but it does not define allowed role values or the expected format, leaving the agent with only the parameter names from 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 uses the specific verb 'Remove' and identifies the resource as 'role/group from a user by email', which clearly distinguishes it from sibling tools like brainkb_assign_role or brainkb_remove_access_rule. The action and target are 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 only includes a parenthetical '(Admin)' to indicate permission level, but provides no guidance on when to use this tool versus alternatives such as brainkb_assign_role or brainkb_revoke_capability, nor does it mention prerequisites like the user existing or the role already being assigned.

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 adds the 'Admin only' permission requirement and implies the capability must have been previously granted. However, it does not disclose error behavior, reversibility, or side effects. With no annotations, the description carries the burden but offers only limited behavioral context beyond the core 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 a single sentence, front-loaded with the admin constraint, and contains zero wasted words. It is appropriately sized for the tool's simplicity.

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 two-parameter revoke tool, the description gives the core purpose and an important admin restriction. However, it lacks usage guidance, parameter detail, and any behavioral consequences, making it minimally viable but not fully complete for an agent to invoke confidently.

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 that 'member' refers to a user and 'capability' is the granted capability, but does not provide formats, valid values, or references to related tools like brainkb_list_capabilities. Minimal value added beyond the parameter names themselves.

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 'Revoke a previously granted capability from a user' with a specific verb and resource, distinguishing it from siblings like brainkb_revoke_role_capability by targeting a user's capability directly. The admin-only note adds a meaningful constraint.

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

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

No guidance is provided on when to use this tool versus alternatives such as brainkb_revoke_role_capability or brainkb_grant_capability. It does not mention prerequisites, valid sources for member/capability values, or any exclusions.

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 must disclose behavioral traits. It only says 'Revoke a capability from a role/group', which restates the purpose. There is no mention of side effects, reversibility, required permissions beyond admin, or how this affects existing grants.

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 concise sentence with no filler, but it is under-specified. It is not verbose, but it also does not carry enough information to be considered well-structured for its purpose.

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 security-sensitive admin mutation tool with no annotations and no output schema, this description is incomplete. It does not explain consequences, return values, or prerequisites. The low parameter count and simple schema reduce complexity, but the lack of behavioral detail makes it inadequate.

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 should compensate. It clarifies that 'role' means a role/group, but 'capability' is not explained. No enums or examples are given, leaving the agent to guess valid values.

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) and the target (a role/group), which makes the purpose understandable. It distinguishes from sibling tools like grant_role_capability by indicating it is the reverse operation, though it does not explicitly name 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?

No guidance is provided on when to use this tool versus alternatives such as revoke_capability or grant_role_capability. The only context is '(Admin only)', which is a permission note rather than a usage guideline.

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 burden of behavioral disclosure. It clearly states the immediate effect ('Takes effect immediately') and the consequence ('the next call using that token fails'). This is non-obvious and valuable, though it doesn't mention reversibility or other side effects.

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 two short sentences, front-loaded with the action and resource, and includes a useful cross-reference. Every word earns its place with no 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 simple revoke operation with a single required parameter and no output schema, the description sufficiently covers purpose, how to use it, and what to expect. The reference to list_tokens rounds out the workflow 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?

The schema only provides the parameter name and type, with no description. The description adds meaning by clarifying that token_id refers to a Personal Access Token and directs the user to brainkb_list_tokens to find the ID. This compensates well for the 0% 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 states a specific action ('Revoke') on a specific resource ('Personal Access Tokens') and identifies the selection mechanism ('by id'). It also references brainkb_list_tokens, which distinguishes it from other token-related operations like create_token or use_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?

It tells you to use brainkb_list_tokens to obtain the token ID, and it clarifies the immediate effect. This gives clear context for when to use the tool, though it doesn't explicitly list any exclusions or alternative tools beyond the listing tool.

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 discloses the admin-only access requirement and the role-scoped nature, but does not mention return format, error handling, or explicitly confirm read-only behavior beyond the verb 'List'.

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 sentence with a parenthetical example, front-loaded with the admin restriction. It is concise with no redundant wording, and the structure is clear.

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 simplicity (one parameter, no output schema), the description covers the essential aspects: action, target, and access level. It does not detail the output structure, but for a straightforward listing tool this is acceptable.

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 lists a single required 'role' parameter with no description (0% coverage). The description's examples ('uk_collaborator', 'Lab Member') add meaningful context about acceptable values, compensating well for the schema gap.

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

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

The description clearly states 'List the capabilities granted to a role/group' with specific examples, using a specific verb and resource. It distinguishes from sibling tools like brainkb_capabilities or brainkb_list_capabilities by explicitly scoping to a role/group.

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 an 'Admin only' restriction, which gives context for who should use it, but it does not explicitly mention alternatives or when not to use it. The usage context is implied rather than stated as exclusions or comparisons with sibling tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds meaningful context by stating that results are access-filtered by space visibility and that anonymous/other users never see private-space data. This goes beyond a simple 'search' statement, though it does not cover pagination behavior or exact match semantics.

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

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

Two sentences, tightly written, with the core purpose and key operational detail front-loaded. Every sentence adds value without redundancy.

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

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

For a 4-parameter search tool with no output schema, the description covers the essential behavior, the scoping parameter, and the access-control caveat. It leaves pagination and result format to the user's inference, but these are standard for search endpoints and the description is otherwise 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?

Schema coverage is 0%, so the description must compensate. It explains the 'space' parameter in practical terms ('scope to one workspace, omit for a full search') and implies 'q' is the full-text query. However, it does not clarify 'limit' or 'offset', though their names and defaults make them reasonably self-explanatory.

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 'Full-text search over the knowledge graphs' with a specific verb and resource, and the access-filtering aspect distinguishes it from related read/search tools like brainkb_read_space and brainkb_sparql. It conveys the exact scope of the operation.

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

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

The description provides practical usage guidance by explaining how to use the 'space' parameter ('Pass space to scope... omit for a full search') and the access restrictions. However, it does not explicitly mention alternatives or when to choose this over sibling tools like brainkb_sparql or brainkb_read_space, so guidance is 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 provided, the description carries the full burden. It discloses the behavioral effect of setting visibility to public or private, and the ownership requirement, adding meaningful context beyond the tool name and schema. It could still mention potential side effects or error behavior, but for a simple setter this is adequate.

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 concise sentence that front-loads the action and includes the essential details (public/private semantics and owner restriction) without wasted words.

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 two-parameter tool with no output schema and no annotations, the description covers the action, the meaning of the visibility values, and the authorization constraint. It is complete enough for an agent to select and invoke the tool correctly, though it could explicitly associate 'slug' with the space.

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 the possible values for visibility ('public' and 'private') and their meanings, but it does not explicitly clarify that 'slug' is the space identifier or provide details about the slug format. This is a partial compensation for the lack of 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 uses a specific verb ('set') with a clear resource ('space visibility') and explains the two states ('public' with anonymous read access, 'private' for members only), distinguishing it from sibling tools like brainkb_create_space and brainkb_read_space.

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 clearly indicates the intended use (setting visibility) and adds an explicit usage constraint with 'Owner only', which informs the agent when this tool is appropriate. However, it does not explicitly compare against alternatives or state when not to use it, so it is slightly below a perfect score.

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

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

With no annotations, the description carries the full burden of disclosing behavioral traits. It clearly states the admin role and capability requirement, which is crucial behavioral context. However, it does not explicitly mention potential side effects (e.g., SPARQL UPDATE/DELETE) or return format, so there is a minor gap in 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 two sentences, with the core purpose stated first, followed by a necessary authorization note and sibling-tool guidance. Every word earns its place; there is no fluff or repetition of schema details.

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

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

For a single-parameter tool with no output schema or annotations, the description covers the essential context: what it does, who can use it, and which alternatives to prefer. It does not describe return values or potential side effects, but given the admin-only nature and the explicit alternatives, it is sufficiently complete for an advanced query 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%, and the description adds no detail about the sparql_query parameter beyond the schema's name/type. While the parameter's purpose is largely self-evident from the tool name, the description does not explain query language version, accepted formats, or constraints, so it fails to compensate for the low 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 'Run an arbitrary SPARQL query', which is a specific verb+resource combination that clearly states the tool's function. It also distinguishes from sibling tools by explicitly naming alternatives like brainkb_search and brainkb_read_space for ordinary questions, making its scope 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 provides explicit guidance on when to use this tool versus alternatives: it requires an Admin/SuperAdmin role with the sparql_admin capability, and it recommends other tools for ordinary questions. This directly addresses usage criteria and exclusions.

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 must disclose behavioral traits. It merely says 'Lift a ban' without mentioning side effects, reversibility, error handling, idempotency, or authentication requirements beyond the admin hint. This is inadequate for a mutation 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 description is a single, front-loaded sentence with no wasted words. It efficiently conveys the action and target.

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, no annotations, and only one parameter, the description still leaves significant gaps: it does not explain the outcome of the operation, what happens if the email doesn't match a banned user, or any prerequisites beyond admin status. This is barely adequate for a simple admin 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 has one param (email) with 0% description coverage. The description's 'by email' clarifies the parameter's role as the user identifier, but adds no format or validation details. While it compensates minimally for the low coverage, it largely restates the property name.

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 the specific action 'Lift a ban' on a user, with the target identified by email. This clearly distinguishes it from sibling tools like ban_user and activate_user.

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

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

The description only includes '(Admin)' as a permission hint, but provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It does not mention that this should be used only when a ban needs to be removed or how it relates to similar admin actions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about failure behavior (staged bytes are KEPT, so retry with ingest_upload) and that 'submitted' sets job_id, which implies polling. However, it does not explicitly state whether the tool is read-only or has any side effects, though the status-check nature is implied.

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 well-structured: a single summary sentence followed by an enumerated list of states with code formatting and clear guidance. Every sentence earns its place, and the front-loaded summary makes the tool's purpose immediately clear.

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 status-check tool with one parameter and no output schema, the description is complete. It explains all possible states and their meanings, including next steps and associated IDs (job_id). No output schema is present, so the description adequately covers what the agent can expect from 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 provides only the parameter name 'upload_id' with no description, and the description does not explicitly explain where to obtain it or its exact semantics. However, the phrase 'one of your staged/submitted uploads' gives context that the ID refers to an existing upload. With 0% schema coverage, the description partially compensates but could be more direct about the parameter.

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

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

The description clearly states the tool returns the state of a single upload, using a specific resource and scope. It distinguishes itself from siblings like brainkb_list_uploads (which likely lists all uploads) and brainkb_job_status (which is for jobs) by focusing on upload state transitions and referencing related tools.

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

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

The description provides explicit guidance on when to use this tool: it describes each state and what action to take next, such as waiting for brainkb_ingest_upload, polling brainkb_job_status, or retrying with brainkb_ingest_upload rather than re-uploading. This effectively tells the agent how to respond based on the state, serving as clear usage instructions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the token is validated, cached for subsequent calls, and never echoed. This gives useful operational transparency about session state and privacy, though it doesn't mention error handling or what happens on invalid tokens.

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 sentences, each adding distinct value: purpose and alternative, validation and caching, and privacy. It is front-loaded with the main action and contains 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 simple two-parameter tool with an output schema, the description covers the core aspect (session-scoped token usage), validation, caching, and privacy. It lacks some context around base_url and prerequisites, but overall it is sufficiently complete for the tool's complexity.

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 the 'token' parameter's format (brainkb_pat_...) and role, but the optional 'base_url' parameter is left entirely unexplained. This is a partial compensation, leaving one parameter without semantic guidance.

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 action: using a Personal Access Token for the current session, with the specific token prefix 'brainkb_pat_...'. It also distinguishes itself from the alternative of setting BRAINKB_TOKEN in config, making its unique role unambiguous even among many sibling auth-related tools.

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

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

The description explicitly frames the tool as an alternative to setting BRAINKB_TOKEN in the config, providing clear context for when to use it. However, it doesn't explicitly state when not to use it or name a sibling tool as a fallback, so it misses the full exclusionary guidance that would warrant a 5.

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

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

With no annotations provided, the description carries the full burden and does well by explaining the output fields and specifically the non-obvious meaning of base_url (server's backend, not the caller's machine). This prevents a potential misinterpretation, going beyond a bare restatement.

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

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

Two sentences, each earning its place: the first identifies the core function, the second provides a critical caveat. No filler words or redundant 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 tool is simple (no params) and has an output schema, so the description only needs to explain the meaning of the returned fields. It covers email, authenticated, session expiry, and the base_url nuance, making it sufficient for an agent to understand the tool's behavior.

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

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

The tool has zero parameters, so there is nothing to explain and the schema coverage is complete. According to the rubric, 0 params earns a baseline of 4; the description adds no parameter info because none is needed.

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 reports the current caller's auth state (email, authenticated, session expiry). It also adds a valuable clarification about base_url, which distinguishes it from other auth-related tools like login/logout.

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 this is the tool to use for checking the current session's authentication details, and the context of sibling tools (login, logout, activate_user) makes that role clear. It doesn't explicitly mention when not to use it, but its read-only nature is evident from the description.

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