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

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds useful context about the risk indicators it identifies, but does not disclose output format, return structure, or data dependencies. This is adequate given annotations, 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 the main verb and resource. It has no redundant phrases and every sentence adds substantive information, making it highly 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 description effectively covers what the tool does and when to use it. With no output schema, it could be improved by stating the return format, but the simple parameter set, optional inputs, and read-only nature make it sufficiently complete for an agent.

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

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

Schema description coverage is 100%, so the parameters are well-documented and the baseline is 3. The description does not add much beyond the schema, though it implies team-level analysis; it does not explain interaction between scope and teamId, but the schema already clarifies this.

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 defines the tool's purpose: analyzing organizational knowledge risk by computing bus factor per team and identifying specific risk indicators like sole owners and single points of failure. This differentiates it from sibling tools such as 'calculate_bus_factor' by positioning a broader risk analysis 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 provides explicit use cases: assessing continuity risk, identifying knowledge silos, and determining team vulnerability to departure. However, it does not include exclusions or mention when to prefer alternative tools, so it falls short of full 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?

Annotations already declare readOnlyHint=true, which is consistent with 'Analyze' and 'Provides recommendations'. The description adds valuable context about the types of analysis performed (bus factor, knowledge concentration, etc.) and the fact that it outputs recommendations, which goes beyond the annotation's safety info. It does not mention data limitations or rate limits, but within the read-only scope it is sufficiently transparent.

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

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

Two sentences, front-loaded with the main action, and every word contributes. It is concise without sacrificing key output 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?

There is no output schema, so the description carries the duty of conveying return values. It lists all key analysis outputs and mentions recommendations, giving a complete picture for a 2-parameter tool with read-only annotations. No gaps in understanding of what to expect.

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

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

Schema description coverage is 100% (both owner and repo have clear descriptions). The description does not add parameter-specific details, but the schema already provides full meaning. Baseline 3 is appropriate because the schema carries the heavy lifting.

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 ('Analyze') and resource ('a GitHub repository's contributor data') and enumerates concrete outputs (bus factor, knowledge concentration, contribution percentages, ownership risk). It is clear and detailed, but does not explicitly distinguish itself from sibling tools like calculate_bus_factor or analyze_knowledge_risk, which is the only difference from a perfect score.

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 for analyzing repository ownership risk and providing recommendations, but gives no explicit guidance on when to choose this tool over alternatives. Sibling tools such as calculate_bus_factor and analyze_knowledge_risk suggest overlapping functionality, and the description does not address trade-offs or scenarios where this tool is preferable.

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?

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds valuable scope information: 'Traverses all relationships' and 'complete ownership sub-graph,' implying an exhaustive read operation. It does not disclose performance implications, but the added scope context goes beyond what annotations provide.

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, highly informative, and front-loaded with the core action. Every clause adds detail about the tool's scope and output types, with zero waste 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 single-parameter, read-only graph-building tool with no output schema, the description explains the full scope (what relationships are traversed) and the intended use case. It does not describe the output format, but that is not required given the absence of an output schema and the graph nature of the result. This is sufficiently complete for an agent to decide when to invoke 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?

The schema description covers 100% of the parameter (employeeId, 'The employee ID to build the ownership graph for'). The tool description does not add further parameter-specific details, so the schema carries the burden. Baseline 3 is appropriate given complete schema coverage.

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

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

The description uses a specific verb ('Build') and resource ('ownership sub-graph for a given employee'), clearly distinguishing it from sibling tools like analyze_repository_ownership (which focuses on repositories) and find_domain_experts (which finds experts). It states exactly what relationships are surfaced, making the tool's purpose unambiguous.

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

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

The description provides a clear use case: 'Use this to visualize an employee's full organizational footprint and identify knowledge concentration risks.' This implicitly sets it apart from more focused tools, though it does not explicitly name alternatives or state when not to use it. The context is strong but lacks explicit 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?

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds conceptual context by defining bus factor, which is helpful, but it does not disclose behavior such as output format, edge cases, or what data is accessed. Given annotations cover the safety profile, a 3 is appropriate.

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 key concept. Every sentence provides needed context. 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?

The tool has a single parameter and clear read-only annotations, so complexity is low. However, there is no output schema, and the description does not mention what the tool returns (e.g., a number, a report, a list). For a calculation tool, it would be helpful to state the output type. Thus it is complete enough for a simple tool but not fully self-sufficient.

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

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

Schema coverage is 100%, with teamId fully documented in the schema. The description only refers to 'a specific team' which adds no new meaning beyond the schema. Thus the baseline 3 applies; the description adds no extra parameter semantics.

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

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

The description opens with a specific verb+resource: 'Calculate the bus factor for a specific team.' It clearly defines what the tool does and provides a concrete metric (minimum number of team members). This clearly distinguishes it from sibling tools like analyze_repository_ownership or identify_hidden_dependencies.

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

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

The description explicitly states when to use this tool: 'when evaluating team resilience, planning for personnel changes, or preparing for knowledge transfer.' This gives clear usage context, though it does not mention alternatives or exclusions, so it misses the top score.

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

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

Annotations indicate readOnlyHint=false, and the description's 'Generate' action aligns with a non-read-only operation. The description adds context about dependency ordering and milestones, but it does not disclose side effects, permissions, or whether the plan is persisted. With annotations present, the bar is lower, and the description adds some but not 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—two sentences with clear front-loading of the main verb and purpose. It efficiently lists what the plan includes without unnecessary repetition 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 2-parameter tool with no output schema, the description adequately explains the output components (systems, people, docs, milestones). It could be slightly richer by specifying whether the plan is generated on-the-fly or stored, but it is sufficiently complete for selection and invocation.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional meaning to the parameters themselves, but it does contextualize how they are used (e.g., role-based and employee-specific planning). This meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose with a specific verb ('Generate') and a specific resource ('structured learning path'). It distinguishes from sibling tools by focusing on onboarding new employees based on organizational knowledge, while siblings cover ownership, dependencies, and transitions.

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

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

It explicitly says 'Use this to accelerate new hire ramp-up using the organization's knowledge graph,' providing a clear usage context. However, it does not explicitly mention when not to use it or differentiate from closely related tools like generate_transition_plan, though the onboarding focus is distinct enough.

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?

Annotations already indicate this is a write operation (readOnlyHint=false), and the description adds context by specifying the merged data types. It does not disclose potential side effects, prerequisites (e.g., employee existence), or edge cases, so it offers only partial transparency beyond the annotations.

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 purpose. Every phrase conveys meaningful information 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 the primary behavior but omits return values (no output schema) and edge cases like missing employees or duplicate merges. Given the simplicity of the tool, it is adequate 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 coverage is 100% with descriptive parameter definitions, so the baseline is 3. The description does not add further parameter-level detail; the mention of 'repository ownership' alludes to owner/repo but does not clarify their specific roles beyond the schema.

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

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

The description uses a specific verb 'Enrich' and clearly identifies the resource (employee profile) and the data merged (commits, pull requests, last activity, repository ownership). This distinguishes it from sibling tools like analyze_repository_ownership or build_ownership_graph, which focus on analysis rather than profile enrichment.

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 conveys clear context—this tool is for adding GitHub activity data to an existing employee profile—and even lists the specific data types merged. However, it does not explicitly state when not to use it or mention alternatives like sync_github_repository, 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?

Annotations already declare readOnlyHint=true, which the description aligns with. The description adds behavioral context by stating it scores and ranks employees, and mentions the data sources searched. This goes beyond the annotation without contradicting it.

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 with no filler. The first sentence states the action and data sources, the second gives usage context and examples. Highly efficient and front-loaded.

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

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

With a single well-documented parameter, read-only annotation, and no output schema, the description fully covers what the tool does, when to use it, and what to expect (ranked experts). No significant gaps remain.

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

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

Schema description coverage is 100% for the single 'domain' parameter. The description provides examples and clarifies the meaning of 'domain', but this is incremental value; the schema already fully documents the parameter, so baseline 3 is appropriate.

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

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

Description clearly states the tool searches through skills, ownership, and involvement to find and rank domain experts. The verb 'search' and outcome 'find domain experts' is specific and distinguishes it from sibling tools that analyze ownership, dependencies, or knowledge risk.

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 use case: 'Use this when you need to identify who to consult for a specific technical or business domain.' This gives clear context but does not explicitly mention alternatives or when not to use it, so it misses the top score.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description adds significant context about what the tool does: analyzes ownership graph, prioritizes handovers, produces a phased timeline. It doesn't mention side effects or persistence, but the non-read-only annotation is not contradicted, and the description explains the behavioral process well.

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, each earning its place: purpose, process, and usage guidance. Front-loaded with the main verb and resource, no filler or redundant 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 no output schema, the description covers what the plan includes (phased timeline, task assignments) and the input scenario well. It's complete enough for an agent to know when to invoke and roughly what to expect, though it could specify the return format in more detail.

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

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

The schema already provides 100% coverage with descriptions for all three parameters (departingEmployeeId, lastDay, successorId). The description reinforces context (departing employee, successor) but doesn't add additional details beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Generate a comprehensive transition plan for a departing employee.' It clearly distinguishes this from sibling tools like recommend_successor or create_onboarding_path by focusing on the full ownership graph analysis and phased timeline.

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 states 'Use this when an employee is leaving or changing roles to ensure continuity,' giving a clear when-to-use. It doesn't mention when-not-to-use or name alternatives directly, but the context is clear enough for most agents.

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?

Annotations already declare readOnlyHint=true, so safety is known. The description adds transparency by detailing what behavioral analysis the tool performs: 'recurring meetings they likely run, approval chains they are part of, cross-team coordination duties, and implicit knowledge that would be lost if they departed.' This goes beyond the annotation to describe the analytical 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 two sentences: the first defines the tool's purpose and scope, the second gives usage timing. Every sentence is informative and there is no redundant or filler content, making it highly 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 has a single parameter, no output schema, and moderate complexity. The description covers purpose, use case, and the categories of findings, which is sufficient for an analyst to decide to call it. It doesn't specify the exact return format, but that's not critical given the tool's nature and the simplicity of inputs.

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

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

Schema coverage is 100% with the employeeId parameter described as 'The employee ID to analyze for hidden dependencies'. The description restates this simply as 'for an employee' but adds no new semantic detail beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Identify' and the resource 'non-obvious responsibilities and hidden dependencies for an employee', which is specific and distinct from sibling tools like analyze_knowledge_risk or calculate_bus_factor. It also enumerates concrete outputs (meetings, approval chains, cross-team duties, implicit knowledge), making the 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?

The description provides explicit use context: 'Use this during continuity planning or before role transitions.' This gives clear guidance on when to invoke the tool, though it does not explicitly mention when not to use it or name alternative 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe, bounded nature is known. The description adds behavioral context by noting it 'Understands natural language questions' and enumerating content types (decisions, documentation, meeting outcomes, technical rationale), which helps the agent anticipate response relevance. No contradiction with annotations.

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 core action, and every word contributes. Examples are compressed and illustrative without redundancy.

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

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

For a tool with a nested context object and no output schema, the description covers the main search purpose and natural language capabilities. However, it omits any mention of the optional scoping parameters (context.aboutSystem, aboutProject, aboutEmployee), which are important for narrowing searches. The schema partially compensates, but the description could have been more 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 50%: the 'question' parameter is well-described with examples, but 'context' and its nested properties are not explained in the description. The description's examples clarify the question parameter but offer no guidance on scoping via context, leaving the agent partially reliant on the schema.

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

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

The description clearly states the tool's purpose: 'Search the organizational knowledge base for decisions, documentation, meeting outcomes, or technical rationale.' It also provides specific examples of natural language questions and explicitly positions it as the primary tool for 'why' and 'how' questions, distinguishing it from sibling tools focused on ownership and dependency 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?

The description gives clear context on when to use the tool: 'Use this as the primary tool for answering "why" and "how" questions about the organization's technical history.' It does not explicitly name alternative tools or exclusions, but the guidance is specific enough to guide appropriate 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?

Annotations already mark the tool as read-only, and the description does not contradict that. It adds context about the ranking criteria but does not disclose additional behavioral traits such as response format or whether it considers all employees. With annotations covering safety, 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 the verb and resource, and contains no filler or redundant information. Every sentence 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?

The description covers purpose, usage, and ranking criteria. It lacks an explicit output format, but the phrase 'score and rank' implies a ranked list, and the tool is relatively simple with two well-documented parameters. This is largely 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 100%, and both parameters are clearly described (roleId and departingEmployeeId). The description adds no extra meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: to score and rank potential successors for a departing employee based on specific criteria (skill overlap, team proximity, system knowledge, capacity). This is a specific verb+resource that distinguishes it from sibling tools like find_domain_experts or calculate_bus_factor.

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 'Use this when you need to identify the best person to backfill or absorb responsibilities,' providing clear context for when to use the tool. It does not name alternatives or exclusions, but the when-to-use guidance is direct and 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?

Annotations already indicate readOnlyHint=false (write operation) and openWorldHint=false (closed world). The description adds valuable context by stating the data is stored in the knowledge graph, revealing the write target and purpose. No contradictions with annotations.

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 main action, and every word contributes meaning. 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 description tells what data is fetched and where it is stored, which is sufficient for a simple 2-parameter sync tool. It doesn't describe return values, but the storage side-effect implies the tool's effect rather than a rich output. Overall complete for its complexity.

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

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

Schema coverage is 100% with both parameters (owner, repo) having descriptions. The tool description adds no additional meaning beyond the schema, so it relies entirely on the schema as expected.

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 specific verbs 'Fetch and sync' with a clear resource ('GitHub repository's data') and enumerates data types (metadata, contributors, commits, pull requests, languages). This clearly distinguishes it from sibling analysis tools.

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

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

The description implies a preparatory role with 'for further analysis', making the usage context clear. However, it doesn't explicitly exclude alternatives or state when not to use it, but the context is sufficient without being verbose.

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