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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds non-derivable context: the returned project is scoped to this particular stdio server instance, not a global or shared selection. That is a meaningful behavioral detail 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?

A single short sentence with the scope qualifier front-loaded and no wasted words.

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

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

An output schema exists, so return values need not be described. The one remaining gap is the edge case where no project is selected in the instance — the description does not say what happens then.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies.

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

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

States a specific verb+resource ('Return the project selected') with a clear scope qualifier ('in this stdio server instance'). It is distinguishable from list_projects and set_active_project by naming the single selected project, though it does not explicitly name those 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?

Usage is implied by the scope phrase ('in this stdio server instance') rather than stated. There is no explicit when-to-use, when-not-to-use, or pointer to the sibling set_active_project/list_projects for the opposite operation.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine context about activeness scoping — both which chunks are returned ('active') and the project-activation prerequisite — but says nothing about error behavior when a chunk isn't active or how many chunks come back.

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

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

Two tight sentences with the core action front-loaded and the scoping constraint second. No filler, though the activeness rule could be phrased slightly more explicitly.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. Still, for a 4-parameter chunk-retrieval tool with zero schema descriptions, the definition leaves the context-window parameters and the meaning of 'active' undefined, which an agent may need.

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

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

Schema description coverage is 0% across 4 parameters, so the description carries the full burden and only partially delivers: it explains the project_id activation rule and implies adjacency via 'adjacent' chunks, but never names context_before/context_after or their default of 1, and gives no meaning for chunk_id beyond the obvious.

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

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

States a specific verb and resource ('Return a selected chunk and adjacent active chunks from the same document'), which is more precise than a bare name restatement. It contrasts implicitly with search_docs by being a single-chunk retrieval, though it never names that sibling to sharpen the distinction.

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 second sentence gives a real precondition ('project sections require that project to be active or passed explicitly'), which tells the agent when project_id matters. It stops short of stating when to prefer this over search_docs or other siblings, so usage is implied rather than instructed.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: results are scoped to the explicitly requested project or the active project, which tells the agent how the query is implicitly filtered. It stops short of noting freshness, caching, or cost.

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

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

A single compact sentence with the core purpose front-loaded before the scoping qualifier. No filler, though the semicolon clause is slightly terse and would read better as two clauses.

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 an output schema present, return values need not be described, and annotations cover the safety profile, so the remaining burden is small. Still, the description omits the sibling differentiation an agent needs and leaves the sole parameter's fallback semantics implicit.

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

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

Schema coverage is 0% and the single parameter (project_id, optional, default null) is undocumented in the schema. The description partially compensates by implying the project falls back to the active project when not explicitly requested, but it never names the parameter or states the null fallback explicitly.

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

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

States a specific verb ('Report') and resource ('official index readiness and synchronization state'), so the agent knows it is a status-read tool. However, it never distinguishes itself from the sibling get_update_status, which plausibly reports a closely related status, leaving the boundary 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The clause about project scope hints at invocation behavior but does not tell the agent when this tool is the right choice over get_update_status or get_active_project.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely useful context beyond them: the default result is cached, refresh=true performs a network check, and critically it explicitly disclaims installing an update. This adds boundary information the annotations do not convey.

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, zero filler, with the core purpose front-loaded and the misleading-interpretation guard ('never installs an update') placed last for emphasis. Every clause earns its place.

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

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

An output schema exists, so return values need no explanation, and the description covers the cache-vs-refresh behavior and the no-install boundary. It stops short of noting failure modes of the GitHub check or cache staleness, which would round it out for an open-world tool.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it explains what refresh=true actually does (a read-only GitHub check) rather than merely restating the boolean. It does not cover the default/reset semantics of refresh=false beyond the word 'cached', but that is a minor gap.

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

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

States a specific verb and resource ('Return the cached release status'), which is unambiguous and self-contained. None of the sibling tools (projects, sync status, docs, products) overlap, so no explicit sibling differentiation is required, but the description also doesn't need to name one.

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

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

Usage is only implied: the default call reads the cache, and passing refresh=true triggers a live GitHub check. There is no explicit 'use this when...' guidance, no precondition or prerequisite information, and no statement of when the cached value is stale enough to warrant a refresh.

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, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds genuine behavioral context beyond that: the 'indexed is false until searchable evidence exists' clause explains a state transition the agent would otherwise have to infer from the data.

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

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

A single front-loaded sentence with no filler, which is appropriate for a no-argument list tool. The trailing clause about 'indexed is false' is compressed to the point of mild ambiguity about which attribute is being described.

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 an output schema present, the description need not document return values, and annotations plus a zero-parameter schema leave little else to explain. What remains slightly thin is the meaning of 'configured' versus 'indexed' and any ordering or filtering of results, but the core is complete.

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

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

The tool takes no parameters, so there is nothing for the description to clarify; baseline 4 applies. Schema coverage is 100% with an empty properties object, confirming no hidden inputs.

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

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

States a specific verb and resource ('List ... BMC products') and adds a meaningful distinction between configured and indexed states. It does not name or contrast any sibling tool, but the resource (products) is disjoint from the sibling set (projects, docs, versions), so differentiation is largely inherent.

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 listing intent implies when to call it, and no sibling tool competes for the same resource, so the implied usage is reasonably unambiguous. However, there is no explicit statement of when to use this versus checking sync/update status, nor any prerequisite or exclusion.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile needs no restating. The description adds one genuinely useful scoping fact — document content is excluded — but says nothing about pagination, ordering, or what 'selectable' means operationally.

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

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

One sentence, front-loaded with the verb and the primary resource, with the scope constraint appended. Zero waste.

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

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

Output schema exists, so return-value explanation is not required, and annotations cover the safety profile. The remaining gap is the undocumented include_archived parameter, which leaves the agent guessing about archived-project behavior despite otherwise adequate context.

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

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

Schema description coverage is 0%: the single parameter include_archived has only a default value and no prose. The description never mentions archived projects, so it fails to compensate for the coverage gap in the one place it could add value.

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

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

States a specific verb (list) and resource (projects), and adds scope qualifiers: 'selectable' and 'their BMC product versions without document content'. This differentiates it reasonably from list_products/list_versions by tying versions to projects, though it does not explicitly name the siblings 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?

'Selectable' weakly implies this is a precursor to set_active_project, but there is no explicit when-to-use, no prerequisites, and no named alternative (e.g., get_active_project for the current selection). The agent must infer the workflow.

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 establish the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's only added behavioral content is the meaning of the 'indexed' state ('false until searchable evidence exists'). That is useful context beyond the annotations, but it is terse and says nothing about pagination or result shape.

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

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

A single front-loaded sentence with no filler; every clause (scope, product form, indexed semantics) contributes. The semicolon-joined second clause is slightly dense but not wasteful.

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 one-parameter list tool with rich annotations and an output schema (so return values need not be explained), the description covers purpose and the one non-obvious state flag. Only usage guidance and pagination behavior are absent, which is a minor gap at this complexity.

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

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

Schema description coverage is 0% and the single 'product' parameter is bare in the schema, so the description carries the load. It does add real semantics by stating the value may be a 'canonical or aliased' product reference, though it gives no format examples for either form.

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 gives a specific verb ('List') and resource ('versions') scoped to 'one canonical or aliased BMC product,' which is clearly distinct from siblings like list_products and list_projects. It does not explicitly route an agent away from any sibling, 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?

Usage is only implied: an agent can infer it should call this when it has a product and wants its version list. There is no statement of when NOT to use it and no named alternative, so it lands at implied rather than explicit 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds the useful scoping behavior that all_relevant excludes unrelated projects, but omits result ranking, top_k default behavior, and how product/version filters interact.

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 with the scope constraint front-loaded and no filler. 'Documentary evidence' is slightly jargonistic but the text is efficiently sized for the schema.

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?

An output schema exists, so return values need not be described. But with 7 parameters at 0% schema coverage and many enum values left unexplained, the description does not supply enough for an agent to filter confidently across product/version/project.

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

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

Schema description coverage is 0% across 7 parameters, so the description carries the burden and largely fails to. It only illuminates the all_relevant value of source_scope and says nothing about query, top_k, product, version, project_id, or document_types.

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

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

Uses a specific verb ('Retrieve') and resource ('documentary evidence') and scopes it to official BMC knowledge plus the effective project, which no sibling (list_projects, get_section, etc.) duplicates. However, it never names the tool as a ranked search or explains what a query actually returns, leaving the retrieval mechanism implicit.

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

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

The only guidance is a narrow caveat that 'all_relevant never searches unrelated projects', which clarifies one enum value rather than when to choose this tool over siblings. There is no explicit when-to-use, when-not-to-use, or alternative 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?

Annotations declare readOnlyHint=false, idempotentHint=true and destructiveHint=false; the description is consistent with those and adds genuinely new context — that the selection is scoped to this stdio server instance and that null reverts to 'official-only' mode. It stops short of saying whether the selection persists across calls or what the response contains, but the added state model is valuable.

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

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

Two short sentences, front-loaded with the action and its scope, with the null-reset behavior immediately following. 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?

An output schema exists, so return values need not be described. For a simple one-parameter stateful setter, the description covers the action, its scope, and the reset path. Minor gaps remain around persistence and where valid project_id values come from.

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

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

Schema coverage is 0% and the schema only declares project_id as a nullable string defaulting to null. The description compensates by explaining the null case ('return to official-only'), which the schema does not convey. It leaves open what a valid non-null project_id looks like (presumably an ID from list_projects), so not a 5.

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

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

States a specific verb and resource ('Select a project') and adds the scoping context ('in this stdio server instance'), which distinguishes it from the read-only siblings list_projects and get_active_project. It's clear what the tool does, though it doesn't explicitly name the sibling 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 one concrete usage rule — 'Pass null to return to official-only' — which tells the agent how to reset state. However, it never says when to call this versus list_projects/get_active_project, nor what prerequisites exist before selecting a project. Usage is implied rather than routed.

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