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 carries the full burden and does so well: caller becomes owner, duplicate slug returns 409, individual spaces require any write-capable role while team spaces require Admin/SuperAdmin or a create_team_space grant, subspaces require manage rights on the parent and inherit its space_type and role propagation, and a subspace cannot be reparented later.

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?

Front-loaded with the action, then organized as a per-parameter breakdown with bold emphasis on critical constraints. It is long, but with 0% schema coverage and no annotations almost every line earns its place; a slightly tighter grouping could still improve scannability.

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

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

For a six-parameter, zero-schema-coverage, no-annotation mutation tool, the description covers preconditions, validation failures, inheritance rules, and role side effects. The absence of an output schema is immaterial since creation semantics and the 409 error path are already described.

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, and it documents nearly every parameter: slug format and global uniqueness with 409 on conflict, visibility's two values and per-space semantics, description's purpose, space_type's two values plus their permission implications, and parent_slug's subspace behavior. Only 'name' is left undocumented, which is self-evident.

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

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

States a specific verb+resource ('Create a workspace/space, or a subspace inside one') and immediately distinguishes the create-space operation from sibling create tools like create_role, create_token, and create_permission. The scope (top-level space vs. nested subspace) is clear from the first sentence.

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

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

Gives clear conditions that select behavior: use parent_slug when you want a subspace, pick space_type='team' vs 'individual' based on permission context. It does not explicitly point to sibling tools for adjacent operations (e.g., add_space_member, set_space_visibility), but the in-tool branch guidance is strong.

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, the description carries the full burden and delivers: it enumerates exactly what is destroyed (named graphs, delta graphs, registry entries, RDF manifest, members, access rules, search entries, SynthScholar reviews), describes deep-first cascade over all subspaces, notes provenance invalidation, and gives concrete failure semantics (403 for non-SuperAdmin, 502 partial-failure message and retry safety). This is exceptional disclosure for a destructive 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?

Front-loads the highest-stakes facts (PERMANENTLY, SuperAdmin, irreversible) before the granular destruction list. Despite its length, every sentence carries unique operational information — cascade order, provenance, param constraint, pre-call guidance, error behavior — with 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?

Given no output schema, the description still names the return signal (`subspaces_deleted`) and describes failure/timeout outcomes. For a high-risk deletion tool with two required params, it covers authorization, blast radius, prerequisites, and recovery — everything an agent needs to call it safely.

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 confirmation mechanism ('confirm_slug must equal slug'), giving real semantic value for the second parameter. The primary 'slug' is left implicit but is self-evident from context, leaving a minor gap in an otherwise well-covered pair.

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

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

States a specific verb and resource with scope: 'PERMANENTLY delete a space and everything in it,' plus the SuperAdmin-only and irreversible qualifiers up front. This clearly distinguishes it from siblings like brainkb_create_space or brainkb_discard_upload. An agent knows exactly what the tool does without opening the schema.

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

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

Explicit when-to-use with prerequisites and an alternative: 'Before calling: show the user the space AND its subspaces (brainkb_space_tree)... get their explicit confirmation.' It names the sibling brainkb_space_tree and forbids autonomous invocation ('Never call it to tidy up on your own initiative'). Nothing is left to inference.

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

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

With no annotations 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 and does so well: it discloses that subspaces are filtered to what the caller may see, members are reported both directly and via inherited_members with their originating parent, and that emails are restricted to members/admins. It stops short of stating error behavior for non-members or inaccessible slugs.

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

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

One dense but front-loaded passage that enumerates the payload first and the auth/visibility caveats last. Given the absence of an output schema, the field inventory earns its space, though the run-on construction is slightly heavy.

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

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

For a tool with no annotations, no output schema, and one parameter, the description effectively substitutes for the missing output schema by enumerating return fields and covers access/visibility rules. The remaining gap is the undocumented input slug.

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 single parameter `slug` has no title or description. The description references `parent_slug` as a return field but never explains what the input slug is, its format, or where the caller obtains it, so it fails to compensate for the coverage 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 concretely defines the resource and its payload — graphs, members, visibility, parent/ancestor slugs, subspaces, and the caller's role — which makes clear this is a detail-fetch for a single space. It implicitly separates itself from list/tree siblings by returning a single space's full record, but it never names those alternatives explicitly.

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

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

There is no explicit when-to-use guidance and no comparison to the closely related siblings brainkb_read_space, brainkb_list_spaces, or brainkb_space_tree. The only usage-adjacent cue is the auth note that public spaces need no login, which is a precondition rather than selection 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 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, the description carries the full burden, and it does disclose meaningful behavior: the tool is gated to Admin/SuperAdmin, and the result includes built-in system reservations (metadata/provenance graphs) that nobody can bind. It stops short of describing return shape, ordering, or what happens for an unauthorized caller, but the auth and immutable-built-in disclosure is substantive.

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

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

A single front-loaded sentence leads with the action ('List reserved named graphs'), then uses a compact appositive to define the concept and a final clause to flag the built-in reservations. No sentence is wasted.

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 with no output schema and no annotations, the description supplies the conceptual grounding (what 'reserved' means, who is allowed) and the special case of built-in system graphs. The main gap is that the shape of the returned list is not described, but an agent has enough to invoke it correctly.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly implies no filtering input is required.

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

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

The description states a specific verb and resource ('List reserved named graphs') and goes further by defining what a reservation means (graph IRIs or prefix IRIs that only admins, or a space's managers/editors, may register or bind). This implicitly separates it from brainkb_list_registered_graphs, but it never names that sibling explicitly, so it falls short of a 5.

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

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

The '(Admin/SuperAdmin)' prefix signals the calling context and the text explains that reservations gate who may register or bind a graph, which implies when an agent would consult this list. However, it never states when to use this versus brainkb_list_registered_graphs or brainkb_unreserve_graph, leaving the choice to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses the auth requirement, the read-only degradation for anonymous callers, the meaning of can_write (role permits ingest, but ingest also needs the capability plus per-space rules), and a privacy behavior (owner email never exposed for public spaces read by non-members). It omits pagination/result-size behavior, keeping it from a 5.

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

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

The purpose is front-loaded and the field-by-field enumeration is largely justified because there is no output schema. It runs long for a zero-parameter read tool, with mild redundancy (is_owner overlaps your_role 'owner'), but each bullet adds usable meaning rather than 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 low-complexity, no-param list tool with no output schema and no annotations, the description supplies the two things an agent actually needs: the auth model and the meaning of each returned field. Only minor gaps remain (ordering, pagination, or result limits are unstated).

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Nothing in the text misleads about inputs.

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 clear verb and resource with explicit scope: 'List spaces the user can see (their own/member spaces + public ones)'. The scope definition implicitly separates it from the close sibling brainkb_list_writable_spaces, but neither that sibling nor brainkb_space_tree is named, so an agent must infer the boundary.

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

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

Gives a concrete use case ('tell the user which spaces they can read vs. write vs. only see as public') and explains the unauthenticated case (public spaces only, read-only; log in for own/member spaces). It stops short of naming alternative tools or stating exclusions, so it is clear context without routing.

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 delivers: it discloses the exact authorization checks (owner/editor membership including inherited parent roles, space write access rule, Admin/SuperAdmin), the meaning of can_ingest=false, and what unmapped_graphs represents. This is unusually rich behavioral context for a read tool.

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

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

Front-loads the core purpose ('Spaces the caller can ingest into') and keeps the field explanations tight. The dense em-dash clause about access checks is information-rich but slightly heavy, keeping it just under fully optimal.

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?

There is no output schema, yet the description describes the returned shape (graphs with descriptions, parent_slug for subspaces, can_ingest, unmapped_graphs). An agent has everything needed to call and interpret the result.

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

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

The tool takes zero parameters, so the schema baseline is 4. There is nothing to add; the description instead spends its budget on return-field semantics, which is the correct allocation.

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

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

States a specific verb+resource: spaces the caller can ingest into, and explains the access basis that defines 'writable'. It explicitly differentiates from a sibling by name ('Use this, not brainkb_list_registered_graphs'), so an agent can distinguish it without opening a schema.

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

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

Provides explicit when-to-use ('to choose where to ingest') and names one alternative to avoid (brainkb_list_registered_graphs). It does not address the closely related brainkb_list_spaces sibling, leaving a minor routing gap, so not 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, 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 carries the full burden, and it does well: it discloses the two-phase discovery model, the shape of returned items (`question`, `notes`, `params`, `example`), and the behavioral rule that required params 'have no default — ask the user rather than guess.' It does not mention permissions or scale limits, but for a discovery/list tool that is a minor omission.

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?

Front-loaded with the core action and the paired run tool before the numbered discovery steps, and every sentence carries information. It is somewhat long at roughly ten lines, but the structure is scannable and no line is 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 discovery tool with no annotations and no output schema, the description covers purpose, workflow, the returned field structure, and both parameters' semantics. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it largely does: `search` is defined as filtering by words in id/question/notes (and its alone-use semantic is stated), and `category` is shown to select a category segment. It leaves unstated what happens when both are supplied and treats defaults (empty string) only implicitly.

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

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

States a specific verb and resource ('Find a canned question BrainKB can answer') and immediately names the paired sibling brainkb_qa_run. An agent can distinguish it from brainkb_qa_run, brainkb_sparql, and brainkb_search without inspecting any schema.

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

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

Explicitly states when to prefer this over writing SPARQL ('vetted against BrainKB's actual vocabulary'), lays out the exact two-step call sequence, and specifies the lone-use condition for `search` ('when none of the descriptions fits'). When-to-use and alternative routing are fully covered.

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 present, the description carries the full burden and delivers: it discloses the auth requirement (same role as brainkb_sparql), the security handling of params (validated and escaped, never spliced raw), and the pagination contract (limit rows from offset, page.next_offset to continue). This is rich behavioral context beyond the schema.

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

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

Front-loaded with the core action, then parameters, then auth, then paging. Three tight sentences with no filler, each conveying distinct information.

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

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

For a 4-param tool with no annotations and no output schema, it covers purpose, param meaning, auth, and paging, and even names a return field (page.next_offset). Gaps remain around what limit=0 means and the result row format, but overall it is close to complete.

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

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

Schema coverage is 0%, so the description must compensate. It explains query_id (an id from brainkb_qa_list), params (name-to-value mapping), and the limit/offset paging behavior. It leaves the meaning of limit=0 (the schema default) and the shape of returned rows unspecified, so it is strong but not complete.

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

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

States a specific verb (Run) and resource (a canned question from brainkb_qa_list, by id), and explicitly names the sibling that supplies the query_id. An agent can distinguish it from brainkb_sparql, which it references as a related but distinct tool.

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

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

Directs the agent to brainkb_qa_list for the id and explains the relationship to brainkb_sparql (same endpoint, same role). It gives clear context for use, but never states an explicit when-to-use-this-vs-sparql rule or any exclusion.

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

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

With no annotations provided, the description carries the burden and handles the most important behavioral trait well: the read-only, auth-optional model for public spaces versus login+membership for private ones. It omits failure modes (invalid slug) and payload-size/pagination behavior, which are relevant for a tool that reads an entire graph.

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

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

Three short sentences, front-loaded with the action and its output format, followed by the access rules. Every sentence earns its place with no 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?

No output schema exists, but the description still names the return format (RDF/JSON-LD), so an agent knows what to expect. Combined with the auth model, this is nearly complete for a simple one-parameter read tool; only slug provenance and error behavior are missing.

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

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

The single required parameter 'slug' has 0% schema description coverage, and the description only implies its meaning via 'a space's graphs' – it never says the slug identifies the space or where to obtain it (e.g., list_spaces). It adds minimal meaning beyond the schema.

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

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

States a specific verb and resource: 'Read all RDF (JSON-LD) in a space's graphs.' It is clear this returns raw graph content rather than a search or query result, though it never explicitly names the sibling tools (sparql, search, list_spaces) it could be confused with.

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

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

Gives concrete when-to-use context: public spaces are readable without login, private spaces require login and membership, and it explicitly warns against prompting for login on public spaces. It does not, however, point to alternatives for content that could be retrieved more cheaply (search, sparql).

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?

With no annotations, the description carries the full burden and does so well: it discloses the role requirement, the visibility of `reason` to refused users, that already-bound graphs remain in place (returned under `already_bound`), and the exact 409 triggers. These are the mutation behaviors an agent needs before invoking.

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?

Front-loaded with the auth scope, then the match_type mechanic, then reason/space_slug, then mutation and error behavior. Sentences are dense but each adds a distinct, call-relevant fact with 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 permission-sensitive mutation with no annotations and no output schema, it covers what an agent needs: who may call it, how reservation scopes work, the side effects on already-bound graphs, the partial response shape via `already_bound`, and failure codes. Nothing essential is missing.

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

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

Schema description coverage is 0%, so the description must compensate and it does: `match_type` is explained with exact-vs-prefix semantics and a concrete prefix example, `reason` gets its purpose, `space_slug` its delegation behavior, and `iri` its role as the graph IRI or prefix. All four parameters carry meaning beyond the bare schema types.

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

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

The description opens with the specific verb+resource ("Reserve a named graph") and the effect ("so other users can't create it"), and the Admin/SuperAdmin qualifier scopes who it is for. It is clearly distinguishable from siblings like brainkb_unreserve_graph and brainkb_list_reserved_graphs.

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

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

It gives clear context for when to use it (preventing other users from creating a graph) and the auth prerequisite, plus the 409 conditions under which it fails. It stops short of naming an explicit alternative tool or a "when not to use" clause, so an agent must infer the routing to unreserve/list on its own.

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, the description carries the full burden, and it delivers the important access-control behavior: results are filtered by space visibility, no login is required, and unauthenticated/anonymous callers only ever see public-space data. It omits pagination/return-shape behavior for limit/offset, which is a minor gap.

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

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

Four short sentences, front-loaded with the core purpose followed by scoping and auth behavior. 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?

No output schema or annotations exist, so the description must cover behavior, and it does cover the access model thoroughly. It falls slightly short by not addressing result pagination or ordering for the limit/offset 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 `space` well (default empty means full search), but `q`, `limit`, and `offset` receive no semantic detail beyond their names and defaults in 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?

States a specific verb and resource: 'Full-text search over the knowledge graphs'. This implicitly separates it from siblings like brainkb_sparql (structured query) and brainkb_qa_run (QA), though it does not name them explicitly.

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

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

Gives clear conditional usage for the `space` parameter ('pass to scope to one workspace, omit for a full search') and states the auth condition for anonymous callers. It stops short of explicitly routing the agent between this and sibling search/query 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 does so well: it discloses the authorization requirement (owner only), the cascading side effect (making a space public makes all subspaces public), the hard constraint that a subspace of a public space cannot be made private, and the resulting 409 error code. These are exactly the consequences an agent must know before calling.

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?

Front-loaded with the core operation, then the auth constraint, then the cascade and error rules. Every sentence adds decision-relevant information with no padding.

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

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

Given no annotations, no output schema, and 0% schema coverage, the description supplies the authorization model, value semantics, cascade behavior, and error condition. The only notable gap is that it does not indicate what the call returns.

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 visibility parameter has no enum in the schema, so the description's enumeration and definition of 'public'/'private' is doing essential work the schema omits. The 'slug' parameter, however, gets no explanation beyond its presence in 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?

States a specific verb+resource (set space visibility) and immediately enumerates the two meaningful values with their semantics ('public' = anyone/even anonymous can read, 'private' = members only). This makes it easily distinguishable from siblings like create_space, delete_space, and 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 states the key prerequisite ('Owner only') and the operating conditions, so an agent knows who may call it. There is no sibling that also sets visibility, so naming no alternative is acceptable, but it stops short of explicit when-to-use framing.

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

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

With no annotations, the description carries the full burden. It does disclose a meaningful behavioral trait: that only subspaces the caller may see are included, plus the recursive depth ('any depth'). However, it omits that this is a read operation, auth requirements, and any pagination or size limits for large trees.

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

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

Two tight sentences, front-loaded with the resource. The second sentence enumerates return fields compactly. Slightly dense but no wasted filler.

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

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

With no output schema, the description usefully enumerates the returned node fields, which is the right compensation. But for a tool with no annotations it omits input-parameter meaning and usage context, leaving gaps an agent must guess at.

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 there is one required parameter (slug) that the description never mentions. The phrase 'A space and every subspace below it' implies a target space but provides no format, source, or semantics for the slug. It fails to compensate for the coverage 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 conveys that this returns a space plus all descendant subspaces as a nested structure, including the output fields per node. That is specific enough for an agent to understand the resource and shape of the result. It stops short of naming siblings (e.g. get_space, list_spaces, read_space) to disambiguate which of these to choose.

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

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

There is no when-to-use guidance and no comparison against alternatives. Given siblings like brainkb_get_space, brainkb_list_spaces, and brainkb_read_space, the agent is left to infer when a full recursive tree is preferable to a flat space lookup. No prerequisites or exclusions are stated.

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

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

No annotations are provided, so the description carries the full burden. It discloses the admin-role requirement, pagination behavior (limit default 0 = server page size of 500, offset, has_more, next_offset), interaction with query LIMIT, truncation with a note, and a COUNT(*) optimization tip. However, it does not explicitly state whether the tool is read-only or can modify data, nor does it mention execution timeouts or error behavior, which are relevant for an arbitrary query 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 front-loaded with purpose, role requirement, and alternatives, then moves to pagination details. Every sentence adds useful information with no filler, and the structure is logical for an agent scanning for key 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 absence of annotations, output schema, and schema descriptions, the definition covers auth, alternatives, pagination, and truncation well. It does not explain the exact shape of the returned data beyond the page envelope (e.g., bindings, boolean, or graph structures), nor does it clarify the dataset or graphs that can be queried, which is a minor gap for a complex arbitrary-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%, so the description must compensate. It thoroughly explains limit (0 = server page size, 500 by default) and offset (starting point), and how they interact with a query's own LIMIT/OFFSET clause. The sparql_query string parameter is adequately conveyed by 'arbitrary SPARQL query' 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?

States a specific verb and resource: 'Run an arbitrary SPARQL query.' Distinguishes itself from siblings by naming brainkb_search, brainkb_read_space, and provenance/delta tools as alternatives for ordinary questions, and by requiring Admin/SuperAdmin. An agent can identify its niche without opening other schemas.

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

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

Explicitly says when to prefer alternatives ('for ordinary questions prefer brainkb_search, brainkb_read_space, or the provenance/delta tools, which need no admin role') and the prerequisite admin role. It also advises using COUNT(*) first when only a count is needed, giving clear usage 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 exist, so the description carries the full behavioral burden. It does disclose a meaningful behavioral fact — the `grounded` flag records whether the quote matched the source verbatim — and implies a prerequisite (an already-ingested review). It says nothing about read-only nature, permissions, or pagination.

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 dense sentences that front-load what the tool returns before listing filters. Little wasted wording, though the parentheses around `grounded` slightly interrupt the flow.

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 8 parameters, no annotations, and no output schema, the description does explain the return shape but leaves pagination (limit/offset) and the `space` scope unexplained, gaps that matter for an agent invoking this correctly.

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

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

Schema coverage is 0% across 8 parameters, so the description must compensate. It maps meaning onto four of them (text→q, claim type→claim, PMID→pmid, grounding→grounded), but limit, offset, and space remain entirely undocumented in both schema and description.

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

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

The description states a specific resource with concrete return fields: evidence spans, quoted text, study, section, relevance, and the grounded flag. It clearly distinguishes itself from data-oriented siblings like records and studies. It stops short of naming which sibling to use instead for adjacent needs.

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?

"Filter by text, claim type, PMID or grounding" implies how the tool is meant to be narrowed but never states when to choose this over brainkb_synthscholar_records, _text, or _studies. Usage is inferable from the filters 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?

No annotations are provided, so the description carries the full burden. It does disclose access filtering ('that you can read') and the shape of the result (included read in full vs. from abstract, or each screening decision with its reason), which is real behavioral context. However, it says nothing about pagination, result limits, or what happens when multiple reviews match.

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 dense sentence, front-loaded with the core question ('Which ingested reviews ... include or screened a study'). The em-dash parentheticals are slightly awkward to parse but every clause 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?

With no output schema, the description must explain return values, and it sketches them (inclusion status or screening decision plus reason). It also covers input constraints, so an agent has enough to call it correctly; remaining gaps are pagination and multi-match 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?

Schema description coverage is 0%, so the description must compensate, and it largely does: it tells the agent the three lookup keys are DOI, PMID, or a title fragment, and adds the non-obvious 6+ character minimum for title matching. That is meaningful value beyond the bare 'Doi'/'Pmid'/'Title' field names, though it does not explain how the three are combined or prioritized.

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

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

States a specific verb+resource: find which ingested reviews include or screened a given study, and what happened to it in each. This is clearly distinct from sibling tools like synthscholar_studies or synthscholar_screening, though it never names those alternatives, so it falls short of a 5.

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

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

Usage is implied rather than stated: the reader infers this answers a cross-reference question about a single study. It gives format guidance for inputs (DOI, PMID, 6+ char title fragment) but never says when to prefer this over synthscholar_studies or synthscholar_records.

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

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

With no annotations, the description carries the burden and does well: it details the returned contents and explicitly discloses what is omitted (long texts, per-study list) and where to find it. It doesn't mention read-only status, auth requirements, or error behavior, but for a retrieval tool it provides strong 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?

Two sentences, front-loaded with the core resource description, then a clarifying exclusion sentence. Dense but every clause adds useful return-value detail; no obvious 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?

The description does a good job describing return values in the absence of an output schema, but it is incomplete on parameter meaning and usage context. An agent still lacks guidance on what 'space' does and how to select this tool over its many siblings.

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 does not mention either parameter. It never explains 'review_id' (required) or 'space' (with default empty string), so it fails to compensate for the complete lack of schema documentation.

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

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

The description clearly identifies the resource as 'one ingested review' and enumerates the returned contents (summary, graph/space, files, search log, verification, screening basis, full-text retrieval). It distinguishes itself from siblings by explicitly excluding long texts and per-study lists, but it lacks a strong action verb and doesn't name sibling tools for contrast.

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 hints at usage by stating what is left out and where to read omitted content ('from the graph or the review page'), which implies this tool is for reviewing metadata rather than full texts or study lists. However, it does not explicitly say when to choose this tool over siblings like list_reviews, studies, or text.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses graph registration, the PROV-O import record contents (who, when, file media type/size/sha256, exclusions), the asynchronous job → job_id lifecycle with polling (brainkb_job_status) and delta reconciliation, the work/ exclusion, the 409 duplicate behavior, and that it reads the server filesystem under MCP_INGEST_ROOT. This is far beyond minimal disclosure.

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

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

Front-loaded with the core action and input definition, and every sentence adds distinct operational value (permissions, job flow, errors). It is dense with nested parentheticals in a single block, which slightly impedes scanning, but there is essentially 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?

No output schema exists, yet the description covers the return signal (job_id) and the follow-up tools needed to track it, plus error semantics (409), permission requirements, and input format. For a two-parameter ingest tool with no annotations or output schema, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: output_dir is defined precisely as the folder holding review.json and review.ttl as the synthscholar skill writes it, and space_slug is characterized as a space the caller may write to as owner/editor. Both required parameters gain real meaning not present in 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?

States a specific verb and resource ('Ingest a SynthScholar review') and immediately defines the precise input: the run's output directory containing review.json and review.ttl. This clearly distinguishes it from the generic siblings brainkb_ingest_files, brainkb_ingest_text, and brainkb_ingest_upload.

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