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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It only states 'Assign or update', implying a mutation, but does not describe side effects such as whether existing assignments are overwritten or additive, what happens if the repo or list does not exist, or if the operation is idempotent. The scope requirement is a prerequisite, not a behavioral trait. This lack of detail is a significant gap for a write 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 a single, concise sentence that immediately states the action and resource. There is no redundant or filler content. It is well-structured and front-loaded with the core 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?

Given the tool's low complexity (only 2 required parameters, no output schema), the description is minimally adequate but misses behavioral details like failure modes, idempotency, or the effect on existing list memberships. An agent could call the tool, but lacks insight into expected outcomes and error conditions. It meets the minimum viable level but no more.

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 parameters (repo_node_id and list_ids) have descriptive entries. The description itself adds no extra semantic meaning beyond what the schema already provides. Per the rubric, a high-coverage schema baseline of 3 is appropriate, and the description does not elevate it.

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: 'Assign or update a repository's membership in native GitHub Star Lists'. It specifies the resource (repository membership) and the target (Star Lists), which distinguishes it from siblings like github_create_user_list or github_get_user_lists. The verb 'assign or update' makes the operation 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 one usage condition: 'requires token with 'user' scope', which is a prerequisite. However, it does not explicitly state when to use this tool versus alternatives (e.g., creating lists or retrieving lists), nor does it mention scenarios where it should not be used. The purpose is clear enough that an agent could infer usage, but explicit routing is absent.

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 it detects dead abandonware, stale projects, and unmaintained dependencies and provides a composite 0-100 score, which is behavioral. However, it does not disclose side effects (likely read-only), caching behavior, API usage, rate limits, or whether it modifies anything. The refresh parameter hints at live API calls but is not explained in the description. This is a partial disclosure, leaving gaps in behavioral 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 two sentences long, with the primary purpose front-loaded in the first sentence and supporting details in the second. Every phrase adds value, with no redundancy or filler. It is 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?

Given the tool's moderate complexity (3 params, no output schema, no annotations), the description covers the main purpose and some behavior but lacks an explanation of the return value or output format. It mentions health scoring but does not specify what the tool returns (e.g., a list of repos with scores, a summary). Also missing are edge cases, limitations, or usage examples. The description is adequate but not fully complete for an agent to anticipate the tool's output.

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

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

Schema description coverage is 100%: all three parameters (filter, refresh, min_health_score) have descriptive schema entries. The description adds minimal extra meaning beyond the schema, such as mentioning the health score scale (0-100) which relates to min_health_score, but does not significantly augment parameter understanding. Per rubric, with high schema coverage, baseline is 3, and the description does not exceed that.

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 'Audit' and clearly identifies the resource 'starred repositories' with distinct focus areas: health, maintenance freshness, and licensing safety. It also mentions detection of dead abandonware, stale projects, and unmaintained dependencies, which distinguishes it from sibling tools like github_list_starred (simple listing) or github_recommend_stack (recommendations). The purpose is 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 clearly implies when to use this tool: when an audit of starred repos' health, freshness, and licensing is needed. However, it does not explicitly exclude other tools or state when not to use it. It provides clear context (audit health) but lacks explicit exclusions or alternatives, so it does not fully meet the 'explicit when/when-not' bar, but it is close.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose dynamic token budgeting, local caching, and speculative prefetching, which are meaningful behaviors. However, it omits cache invalidation/refresh semantics, rate-limit or auth implications, and what the returned payload looks like.

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 dense sentence that packs the core purpose and three behavioral traits without filler. It is concise and front-loaded, though the jargon-heavy phrasing reduces readability slightly.

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 complex 9-parameter tool with no annotations and no output schema, yet the description only names high-level features. It lacks usage guidance, cache/refresh behavior, relation to sibling tools, and any indication of return values or pagination semantics.

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%, so the baseline is 3. The description's phrases like 'token budgeting', 'caching', and 'prefetching' map to schema parameters but do not add meaning beyond what the parameter descriptions already provide.

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

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

The description states a specific verb and resource: it fetches starred repositories plus distilled READMEs in batch. It is clear enough to differentiate from simpler siblings like github_list_starred and github_get_readme, though it does not explicitly name or contrast them.

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 guidance on when to use this tool versus alternatives such as github_list_starred or github_get_readme. The description implies a high-performance batch use case but does not state when not to use it, prerequisites, or trade-offs.

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 state that memory and disk caches for stars and READMEs will be cleared, implying destructive cache deletion, but it does not disclose consequences such as re-fetch behavior, scope of impact, or irreversibility.

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 filler. Every word contributes to the meaning, and the verb-object construction is immediately understandable.

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 maintenance tool, the purpose is adequately stated, but the description is minimal. Without annotations or an output schema, it lacks details about side effects, return behavior, or what happens after the cache is cleared.

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 full schema coverage, so the baseline of 4 applies. The description does not need to explain parameter semantics, and it adds no conflicting parameter information.

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

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

The description uses a specific verb ('Clear') and resource ('memory and disk caches') scoped to 'GitHub stars and READMEs.' It is distinct from the sibling tools, though it does not explicitly name a sibling or state what it is not.

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

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

The description gives no guidance about when to use this tool versus alternatives, no conditions, and no exclusions. An agent must infer that it is a maintenance action for stale caches.

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 token scope requirement and the creation action, but does not describe the response format, success/failure behavior, potential side effects, or rate limits. For a mutation tool, this is a significant gap in behavioral 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, well-structured sentence that front-loads the action and key requirement. It is concise with no redundant words, earning a perfect score for efficiency.

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 simplicity of the tool (3 parameters, all described) and the absence of an output schema, the description is mostly adequate but misses critical context: it does not state what the tool returns (e.g., the created list object or an ID) or how errors are handled. This leaves an agent uncertain about the post-call state.

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%, meaning all parameters (name, is_private, description) are already documented with clear descriptions in the input schema. The tool description adds no extra meaning beyond what the schema provides, 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 action (Create), the resource (native GitHub Star List), and the platform (github.com), and distinguishes it from sibling tools like github_get_user_lists (retrieval) and github_assign_repo_to_lists (assignment). It also mentions the token scope requirement, leaving no ambiguity about what the tool does.

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

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

The description implies usage (create a list) but does not explicitly state when to use this tool versus alternatives or when not to use it. For a simple creation tool, the intent is fairly obvious, but there is no guidance on conditions that would make a different tool more appropriate, such as updating or deleting lists.

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 notes that the tool saves/updates a file, but it does not warn about overwrite behavior, side effects on existing files, or any destructive implications, leaving significant behavioral ambiguity for an agent.

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 one concise sentence with no redundant clauses. It front-loads the core action and resource before elaborating on content, though 'organized' is mildly redundant filler and the structure is minimal rather than excellent.

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 moderate-to-high complexity with five parameters, nested repository objects, merge/overwrite modes, and an alternative parameter name, yet no annotations or output schema. The description does not explain mode behavior, file effects, return values, or when to use the compiled_categories parameter, leaving important operational context 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 100%, so the schema fully documents every parameter and the baseline is 3. The description adds little beyond the schema, mentioning only summaries and tags, which are already covered by the repo object's 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 ('Save or update') with a clear resource ('organized Markdown catalog file') and explains the file's contents ('grouping repositories by category with summaries and tags'). It is clear enough to differentiate from siblings like get_user_info or list_starred, though it does not explicitly name or contrast any sibling 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?

The description implies usage: when the user wants to persist a categorized Markdown catalog of repositories. However, it gives no explicit when-to-use guidance, no exclusions, and does not explain when this tool should be chosen over related tools like assign_repo_to_lists or create_user_list.

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 full transparency burden. It discloses trigger conditions and two policies, but 'force-reduces' implies a mutating/recovery action without stating side effects, reversibility, permissions, or what actually happens to the session and workers. For a 'force' operation, 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?

Two short sentences, front-loaded with the 'Resilience Tool' category and minimal redundancy. Every sentence contributes useful context, and there is no filler.

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

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

For a two-parameter recovery tool, the trigger condition and policy options are present. However, there is no mention of return value, side effects, or how this relates to the normal orchestration flow, and no output schema compensates. It is adequate but leaves operational 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 input schema documents both parameters at 100% coverage with clear descriptions. The description's second sentence only paraphrases the missing_worker_policy enum, adding no new parameter semantics beyond what the schema already provides.

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 operation ('force-reduces an orchestration session') and immediately scopes it to failure conditions ('orphaned, times out, or fails'). This clearly distinguishes it from normal orchestration and status-checking sibling tools, even though 'reduce' is somewhat domain-specific.

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

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

The description explicitly frames the tool as a 'Resilience Tool' and defines the triggering scenarios: worker orphaned, timeout, or failure. It does not name sibling alternatives or provide when-not-to-use guidance, so it stops 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 provided, so the description carries the burden. It discloses that this is an inspection operation ('Inspect current progress...'), implying read-only behavior. However, it doesn't disclose what happens if the session_id is invalid, whether the operation has side effects, or what the response format looks like. The description adds some behavioral context but not rich detail.

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 front-loads the action ('Inspect') and lists the specific aspects covered. It is concise and every word earns its place, though it could be slightly more 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 simple one-parameter inspection tool, the description is mostly complete. However, with no annotations and no output schema, it doesn't explain what the response contains or how to interpret the 'worker state machine' and 'compiled categories'. An agent might benefit from knowing the return shape or any prerequisites (e.g., session must exist).

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 the single parameter (session_id as 'Orchestration session identifier'). The description doesn't add meaning beyond the schema, but with full coverage, the baseline 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 uses a specific verb ('Inspect') and names the resource ('orchestration session') plus the specific aspects it covers (progress, completed workers, worker state machine, compiled categories). It is clear about what the tool does, though it doesn't explicitly differentiate from sibling tools like github_get_worker_chunk or github_force_reduce_session.

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

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

The description implies this is for checking the status of an orchestration session, which is a read-only inspection. It doesn't explicitly state when to use this vs alternatives like github_get_worker_chunk (which likely gets a specific worker's chunk) or github_force_reduce_session. The context is clear but no exclusions or alternatives are named.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses caching (ETag, 24h TTL), semantic distillation, and context budget controls. However, it does not explicitly state that the operation is read-only, nor does it mention auth requirements, rate limits, or error behavior. The disclosed behaviors are useful but incomplete for a tool with zero annotation coverage.

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 front-loads the core action ('Fetch the README markdown') and then lists the key features. No filler or redundant phrasing. 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 100% schema coverage and no output schema, the description does not need to detail return format. However, for a tool with no annotations, it lacks critical usage context: it does not mention that this is a single-repo fetch versus batch, any prerequisites (e.g., repo must exist), or error handling. The description is functional but leaves the agent to infer when to use it relative to 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 coverage is 100%, so parameters are already documented. The description adds meaning by introducing 'semantic distillation' (mapping to the distill parameter) and 'context budget controls' (mapping to profile and max_chars), which help an agent understand the intended effect of these parameters beyond their raw schema definitions.

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

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

The description states a clear verb 'Fetch' and resource 'README markdown for a repository'. It's specific and unambiguous, but it does not explicitly differentiate from the sibling tool github_batch_get_starred_with_readme, which likely performs a similar fetch in bulk. The purpose is clear but sibling distinction is left to inference.

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 explicit guidance on when to use this tool versus alternatives. It mentions caching and distillation, but does not state when to prefer this over batch tools or other retrieval methods. No when-not-to-use conditions are given.

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 usefully reveals that results are cached with a 15-minute TTL and that a refresh parameter exists to bypass the cache, but it does not mention auth failure behavior, rate-limit implications, or explicitly confirm there are no 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 a single, well-structured sentence that states the primary purpose, the additional computed value, and the caching behavior. There is no filler or redundant 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 simple one-optional-parameter read tool with no output schema, the description gives enough context to invoke it: what is returned at a high level, the caching behavior, and the existence of a refresh override. It could optionally detail the response shape or auth failure handling, but this is not essential for correct invocation.

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

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

Schema description coverage is 100%, and the refresh parameter is already clearly documented in the input schema as 'Force live refresh from GitHub API, bypassing cache.' The main description's cache/TTL mention reinforces this but does not meaningfully add 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 names a specific verb ('Get') and resource ('authenticated GitHub user details') plus the additional computed value ('total count of starred repositories'). It is distinct from sibling tools like github_list_starred, which clearly targets the actual starred repo list rather than user info.

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 intended use is implied by the tool name and description: retrieve user info and star count. However, there is no explicit guidance about when to prefer this over github_list_starred or github_get_user_lists, and no exclusions or alternative 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 explaining behavior. It only says 'Get all native GitHub Star Lists', which implies a read-only operation, but it does not disclose caching behavior, the meaning of 'current', rate limits, authentication requirements, or response details.

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, direct sentence with no filler. It front-loads the resource being retrieved and adds clarifying scope ('created by the authenticated user') and content ('current items and IDs') efficiently.

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 optional parameter and no required parameters, the description is adequate but leaves gaps. It does not clarify the refresh/caching behavior, output shape, or any behavioral caveats, which is more important because there is no output schema and no annotations.

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 boolean 'refresh' parameter, so the schema fully documents it. The description does not add parameter-specific meaning, but the baseline is appropriate given full 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 identifies the tool as a getter for all native GitHub Star Lists belonging to the authenticated user, including items and IDs. It is specific about the resource and scope, though it does not explicitly contrast itself with sibling tools like github_list_starred or github_create_user_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 given about when to use this tool versus alternatives. There is no mention of when to prefer this over github_list_starred or github_create_user_list, nor any exclusions or prerequisites.

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 indicates a read-like operation ('Fetches') and mentions 'frozen snapshot' suggesting immutability, but it does not explicitly state that it is non-destructive, whether authentication is required, or what happens on invalid session_id/worker_id. It also does not mention any side effects or rate limits. Since it appears to be a safe read operation but this is not explicitly confirmed, the description 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 a single sentence that front-loads the core purpose and includes the key qualifiers ('exact frozen snapshot chunk', 'assigned to this worker', 'including pre-distilled READMEs'). There is no redundancy or fluff; every word contributes to clarity.

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 role in a distributed orchestration workflow and the absence of an output schema, the description does not explain the return format or what an agent should do with the fetched chunk. It also does not mention any prerequisites or ordering relative to sibling tools (e.g., whether it must be called after github_orchestrate_workers). While it clearly states what it fetches, it omits important operational context for an agent to use it correctly in the larger workflow.

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 each parameter is already documented (session_id, worker_id, profile). The description reiterates session_id and worker_id but adds no new meaning beyond the schema. The mention of 'pre-distilled READMEs' hints at the profile's effect on README budget, but that is not directly parameter semantics. Baseline 3 is appropriate when the schema covers parameters 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 states a specific verb ('Fetches'), a precise resource ('frozen snapshot chunk'), and the assignment criteria (session_id and worker_id). It also notes the inclusion of 'pre-distilled READMEs,' which further clarifies content. The 'Worker Tool' prefix and the mention of 'assigned to this worker' distinguish it from orchestration or submission tools among siblings.

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

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

The description labels it a 'Worker Tool' and references 'assigned to this worker,' implying it is for a worker agent to retrieve its own chunk during a distributed process. It does not explicitly name alternatives or state when not to use it, but the sibling list (e.g., github_orchestrate_workers, github_submit_worker_digest) and the phrasing provide strong contextual guidance. Slight gap in 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?

Since annotations are entirely absent, the description carries the behavioral disclosure burden. It adds useful context by mentioning the 10-minute TTL cache, which aligns with the 'refresh' parameter breathing room. However, it does not mention authentication, rate limits, response shape, or that this is purely read-only, leaving some important operational traits undisclosed.

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

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

The description is a single front-loaded sentence: it states the purpose immediately and appends the cache behavior in a parenthetical. There is no filler or redundant repetition of schema information, making it easy to scan and process.

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 five optional parameters, full schema descriptions, and no output schema, the description provides the core function and a notable behavioral trait. But it leaves 'details' vague, does not explain return format or pagination defaults beyond the schema, and gives no relationship to sibling tools like github_batch_get_starred_with_readme, so an agent may not fully understand trade-offs.

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 already describes all five parameters, including defaults and constraints, so schema coverage is 100% and the baseline is 3. The description does not add new meaning for page, sort, per_page, or direction; its only parameter-related addition is the cache TTL context that explains the refresh parameter's purpose.

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 ('Fetch') and a clear resource ('starred repositories'), and explicitly mentions pagination and details. However, it does not distinguish itself from siblings like github_batch_get_starred_with_readme or github_search_stars, so an agent may still need to infer which list-style tool to use.

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 guidance about when to use this tool versus alternatives. With siblings such as github_search_stars, github_batch_get_starred_with_readme, and github_export_catalog, the description gives no explicit selection criteria or exclusions. The only implied context is the word 'list', which is not enough to route an agent confidently.

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 a key behavior: taking an immutable frozen snapshot to prevent mid-run mutation drift, which is valuable. However, it does not disclose whether the tool has side effects like persisting session state or creating resources, which is important for an orchestration tool with no 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 a single, dense sentence that front-loads the 'Map-Reduce Step 1' context. Every clause contributes meaning: the immutable snapshot, taxonomy extraction, and chunk plan generation. 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?

While the description covers the core behavior, it lacks details on what the tool returns (since no output schema exists) and how the generated 'worker chunk plans' are used in subsequent steps. It also doesn't mention prerequisites like authentication or session handling, which are critical for an orchestration tool. It is adequate for basic invocation but incomplete for a complex multi-step workflow.

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 100% coverage of all four parameters, so the baseline is 3. The description adds some context by mentioning 'balanced worker chunk plans' which relates to num_workers, but does not explicitly explain any parameter. It does not go beyond the schema to clarify usage nuances.

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 role as 'Map-Reduce Step 1' with specific actions: takes a frozen snapshot, extracts taxonomy, and generates worker chunk plans. It names the resource (starred repos) and distinguishes itself from siblings like github_get_worker_chunk and github_force_reduce_session by being the initialization step.

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 labels itself as Step 1 of a map-reduce workflow, indicating it should be called before other steps like github_submit_worker_digest or github_force_reduce_session. It does not mention alternatives explicitly, but the context of sibling tools and the 'Step 1' label give 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?

With no annotations, the description carries the full behavioral disclosure burden. It does indicate advisory behavior ('recommends', 'copy-paste installation commands') and implies read-only operation, but it does not explicitly state that it does not modify state, install anything, require special auth, or behave unexpectedly when no starred tools 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?

The description is a single, readable sentence with the key purpose front-loaded. The opening phrase 'AI Agent Tech-Stack Recommender' is slightly redundant with 'recommends', but the overall structure is focused and free of 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 recommendation tool with only one required parameter, the core input and output are reasonably clear. However, with no output schema and no annotations, the agent is left guessing at return format, default behavior, and edge cases such as no recommendations or language restrictions. The description covers the essentials but not the full call 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 100%, so the schema already documents all three parameters. The description ties 'project brief or task description' to task_description and mentions commands/rationale, but adds little semantic value beyond the schema for language or max_recommendations.

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 ('recommends') and resource ('vetted starred tools and libraries'), plus the triggering context ('project brief or task description'). This distinguishes it from siblings like list_starred or search_stars, which are about retrieving data rather than synthesizing recommendations.

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 it—when a project brief or task description exists—but provides no exclusions, prerequisites, or explicit alternatives. It does not reference any sibling tool or explain when one of the many starred-repo tools would be more appropriate.

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

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

With no annotations, the description carries the behavioral burden. It discloses useful traits: offline/local execution, zero dependency, BM25 hybrid scoring, and sub-5ms latency. It does not mention side-effect status, return format, or whether results are sorted, so transparency is partial.

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 the core function front-loaded. The second sentence adds useful performance and implementation context, though it is slightly promotional.

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 plus fully documented schema is enough for basic invocation. However, there is no output schema and no return-value semantics, and the tool is not placed relative to sibling tools, leaving some context gaps for an agent choosing among many starred-repo tools.

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 baseline is 3. The description does not add parameter-specific details beyond the schema, though mentioning BM25 and weighted field scoring gives some context for how query and min_score are interpreted.

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 ('starred repositories') and the activity ('concept & problem-to-solution discovery'), making it clear this is a search/discovery tool. It does not explicitly use the verb 'search' or differentiate itself from siblings like github_list_starred, so it stops 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 description implies usage for fast, local discovery across starred repositories, partly distinguishing it from simple listing. However, it does not explicitly state when to use this tool versus alternatives like github_list_starred or github_recommend_stack, nor does it provide exclusion conditions.

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, and it does: it validates against baseline taxonomy, prevents race conditions, and handles GraphQL list sync fallback. This goes beyond a simple 'submit' and informs the agent of side effects and safeguards. However, it does not mention error handling, idempotency, or what the response indicates, which would be useful for a mutation-like 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 a single, dense sentence that front-loads the step number and core action, then adds critical behavioral constraints. Every clause adds value: the step context, the submit action, validation, race conditions, and fallback. No filler or repetition.

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

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

For a submission tool with no output schema and no annotations, the description covers the core action and key behaviors but omits important operational details such as the expected response (success/failure), what happens on validation failure, and any prerequisites (e.g., session state). Given the tool's role in a multi-step workflow, an agent might need more guidance on post-submission expectations.

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 all parameters (worker_id, session_id, analyzed_repos) are already documented with their types and purposes. The description adds minimal new semantic meaning; it references 'distilled category & pitch digest' which aligns with the schema but does not enrich parameter details further. Baseline 3 is appropriate when the schema carries the full load.

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 is the submission step for distilled category and pitch digests in a map-reduce workflow. It mentions specific responsibilities (validation, race condition prevention, GraphQL fallback) that distinguish it from orchestration, reduction, and assignment tools in the sibling list. The verb 'submit' and resource 'worker digest' are 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?

The description situates this as 'Map-Reduce Step 2' and notes it is for sub-agents to submit their digests, implying it is used after analysis and before reduction. It does not explicitly list alternative tools or when not to use it, but the pipeline context provides clear situational guidance. A small gap is the lack of explicit exclusions or alternatives.

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