ProjectBrain

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

With no annotations, the description carries the full burden. It discloses two key behaviors: write-only and no reading of source bodies. But it does not mention what happens on conflict (e.g., overwrite vs. fail), required permissions, or side effects like triggering any downstream processes. This is adequate but not thorough.

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, containing only essential information without any fluff. It is efficient and front-loaded, immediately stating the core action.

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

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

Given the tool has 9 parameters, no output schema, and no annotations, the description is far too minimal. It lacks details on parameter meanings, return values, error conditions, and usage examples. For a tool of this complexity, the description is incomplete and leaves the agent with many unknowns.

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

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

Schema description coverage is 0%, meaning the schema provides no descriptions for any of the 9 parameters. The description offers no additional explanation of parameters like applies_to, risk_level, review_state, claim_type, confidence, source, or claim_id. The agent is left to infer from names alone, which is insufficient for correct invocation.

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

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

The description clearly states the action (add), resource (experience claim), and scope (local human, imported project). It differentiates from siblings like archive and review by implying creation. However, the term 'human experience claim' may be domain-specific and not fully self-explanatory.

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 context that it writes only to local storage and does not read source bodies, which helps in deciding when to use it. However, it does not explicitly mention when not to use this tool versus alternatives like projectbrain_review_experience_claim or projectbrain_archive_experience_claim, leaving some 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?

Without annotations, the description must convey behavioral traits. It indicates that archiving retains storage, but does not explain whether the claim is hidden, accessible, reversible, or any side effects on related 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 single sentence of 10 words, concisely stating the core functionality. Every word contributes to the purpose, with 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?

The tool has 3 parameters and no output schema or annotations, yet the description omits details on what archiving entails, the effect on queries, and the purpose of the optional 'reason' parameter.

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

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

Schema description coverage is 0%, and the description adds no information about the parameters (project_id, claim_id, reason). Their meanings are entirely left to the schema field names.

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 ('archive'), the object ('local experience claim'), and the nuance ('keeping it in ProjectBrain storage'), which distinguishes it from sibling tools like add, review, or 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?

No guidance is provided on when to use this tool versus alternatives, such as when to archive vs. delete or review. There are no scenarios or prerequisites mentioned.

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

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

No annotations are provided, so the description must bear the burden of behavioral disclosure. 'Build' suggests creation/mutation, but there is no information about side effects, required permissions, reversibility, or any behavioral traits beyond the basic 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, concise and to the point. It front-loads the core action. However, it may be too terse, missing opportunities to add value without significant bloat.

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 4 parameters, no output schema, and no annotations, the description is too brief to be complete. It omits context about what a Context Pack is, the expected output format, and any behavioral implications of the 'Build' 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 input schema has 4 parameters with 0% description coverage, and the tool description adds no parameter-specific information (e.g., what 'task' format, what 'output_format' options mean). The description fails to 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 ('Build') and resource ('Context Pack from local ProjectBrain facts'), making the tool's purpose clear. However, it does not explicitly distinguish itself from siblings, which have different actions like adding or archiving claims.

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 phrase 'task-scoped' implies usage when building a context pack for a specific task, but there is no explicit guidance on when to use this tool versus alternatives, no when-not conditions, and no mention of prerequisites or constraints.

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

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

No annotations are provided, so the description must carry the full burden. The single sentence does not disclose any behavioral traits such as whether the tool is read-only, what data it accesses, performance implications, or side effects. This is a significant 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?

The description is a single sentence with no redundancy, but it achieves conciseness at the expense of critical information. Under-specification is not true 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?

Given six parameters, no output schema, and no annotations, the description is extremely incomplete. It fails to explain what the analysis returns, how to use the parameters effectively, or any behavioral details. Agent cannot use this tool correctly without guessing.

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

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

The schema has 0% description coverage for parameters, and the description does not explain any of the six parameters (project_id, task, changed_files, etc.). The agent receives no additional meaning beyond the raw schema names.

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 'Analyze likely local project impact for changed files or symbols,' which clearly identifies the tool's purpose. It differentiates from siblings like 'projectbrain_add_experience_claim' or 'projectbrain_inspect_policy' by focusing on impact analysis.

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

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

No guidance on when to use this tool versus alternatives (e.g., 'projectbrain_review_git_diff' or 'projectbrain_inspect_policy'). No mentions of prerequisites, limitations, or scenarios where other tools would be 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?

Without annotations, description carries full burden. It mentions only that it runs on local files and does not upload source code, but lacks details on error handling, overwrite behavior, 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?

Two sentences, front-loaded with key information, but omits essential parameter details.

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

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

Given 8 parameters, no output schema, and no annotations, the description is severely incomplete. It lacks details on return values, side effects, and parameter usage.

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

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

Schema description coverage is 0% and the description provides no explanation for any of the 8 parameters, including required ones like project_id and project_path.

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

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

The description clearly states it imports CodeGraph facts from a local repository into the ProjectBrain store, with a specific verb and resource. It distinguishes itself from siblings by focusing on importing projects, not adding claims or other operations.

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

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

No guidance on when to use this tool vs alternatives like projectbrain_context_pack or projectbrain_list_projects. No prerequisites or exclusions mentioned.

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 states 'inspect' (implying read-only), but does not confirm side effects, authorization needs, or what 'local output policy' entails. The description is too brief to be informative.

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, efficient sentence with no extraneous information. However, it sacrifices necessary detail for brevity, making it less useful than a slightly longer description would be.

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

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

Given the lack of output schema and annotations, the description should explain what the tool returns or the behavior of inspection. It does not, leaving the agent without knowledge of the output format or 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 input schema has one parameter (project_id) with 0% description coverage, but the description adds only minimal context: it mentions the policy is for an imported project. No details on parameter format, constraints, or how it affects the inspection.

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 (inspect) and the resource (local output policy for an imported project), distinguishing it from sibling tools that perform different operations like adding, archiving, or listing claims.

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 prerequisites for having an imported project or when inspecting a policy is appropriate. The description is silent on 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?

Discloses default archived filter, but lacks permissions info or other behaviors; acceptable for a simple list 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?

Two precise sentences 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?

Covers purpose and default filtering, but lacks return format and error handling; adequate for a simple 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 has 0% description coverage; description doesn't explain parameters beyond names and default behavior for archived.

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 experience claims for a project and distinguishes from sibling add/archive tools.

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

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

No explicit guidance on when to use this vs alternatives like add or archive; only implied by listing 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?

The description does not disclose any behavioral traits beyond the basic listing functionality. With no annotations, the description carries the full burden, but for a simple list operation with no parameters, the minimal behavioral info is adequate. It does not state whether the operation is read-only or has side effects, but it is implied.

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

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

The description is a single concise sentence that conveys the core purpose without any extraneous words. 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?

Given the tool has no parameters and no output schema, the description is largely complete. It explains what the tool does (list imported projects). However, it does not mention the return format or any limitations, which would be helpful but not critical for such a simple 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 description coverage is trivially 100%. The description adds no parameter information, which is acceptable since there are none to explain. Baseline 4 for zero parameters.

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

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

The description clearly states the tool lists projects that have been imported into the local ProjectBrain store, specifying the verb 'list' and the resource 'projects'. It implicitly distinguishes from sibling tools like projectbrain_import_project and projectbrain_list_experience_claims by focusing on projects. However, it does not explicitly differentiate itself from other list tools.

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

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

No guidance is provided on when to use this tool versus alternatives such as projectbrain_list_experience_claims. There is no mention of prerequisites, typical use cases, 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?

No annotations exist, so the description carries full behavioral burden. It states 'Update' but does not disclose side effects, permissions needed, idempotency, or error states. A mutation tool with 9 parameters requires more transparency about what 'local review metadata' entails and whether other data is affected.

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, which is concise but vastly underspecified given the tool's complexity (9 parameters, no output schema). It does not earn its brevity; it sacrifices necessary detail. A minimal viable description for this tool would require multiple sentences.

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 9 parameters, no output schema, and no annotations, the description is inadequate. It fails to explain the tool's purpose in the context of the sibling tools, the role of each parameter, or the expected outcome of the update. This leaves the AI agent with insufficient information to correctly invoke the tool.

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

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

Schema description coverage is 0%. The description adds no meaning to the 9 parameters beyond their names and types in the schema. For example, it doesn't explain what 'applies_to', 'confidence', or 'source' mean in context. Parameter semantics are entirely undocumented in the 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?

Description clearly states verb 'update' and resource 'local review metadata for an experience claim'. It distinguishes from sibling tools like 'add' and 'archive' by implying modification of existing data. However, it does not explicitly contrast with siblings, and the term 'review metadata' could be more precise.

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 on when to use this tool versus alternatives. No mention of prerequisites, typical use cases, or when not to use it. Given the sibling tools (add, archive, list), the description should provide context for selection.

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

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

With no annotations, the description carries the full burden and explicitly states it reads changed file names from local git only and does not read or upload source bodies. However, it omits details on permissions, side effects, or response format.

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

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

Two sentences, front-loaded with purpose, no unnecessary words. Efficient 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?

For a tool with 9 parameters (0% schema coverage), no output schema, and no annotations, the description is too brief. It fails to explain parameters, output, or usage context, leaving the agent underinformed.

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, but it adds no explanation for any of the 9 parameters. The mention of 'local Git changes' loosely relates to some parameters but provides no semantic mapping or syntax guidance.

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

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

The description clearly states the tool analyzes impact for local Git changes in an imported project, distinguishing it from sibling tools by specifying 'local Git changes' and clarifying it reads only file names, not source bodies.

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 explicit guidance on when to use this tool versus alternatives like impact_analysis or context_pack is provided. Usage is implied but not explained with when-not or alternatives.

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