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 a useful prerequisite by specifying the builds must already be fetched, and that comparison is file-level and language-scoped. It omits whether the operation is read-only, what the return payload looks like, and any permission needs.

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

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

Two tight sentences, front-loaded with the mechanism and closed with the recommended use case. No filler or restatement of the tool name.

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

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

With no annotations, no output schema, and 4 params at 25% coverage, the description does cover the core mechanism but leaves the required build-id params and return shape unexplained. Adequate for orientation but incomplete for reliable 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 coverage is only 25%, with just project_id documented. The two required params (from_build_id, to_build_id) and language are undocumented in both schema and description; the phrase 'per language' hints at the language param's role but adds no format or default detail.

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

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

States a specific verb (compare) and resource (two fetched builds' emitted files) with the comparison dimension spelled out (added, removed, changed), plus a per-language scope. An agent can distinguish it from list_builds/get_build, which only enumerate or fetch individual builds.

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 primary way to judge a generator change' gives clear positive guidance on when to reach for this tool, effectively positioning it above sibling build tools. It does not, however, name an alternative or state exclusions (e.g. when to prefer list_generated_files instead).

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

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

With no annotations, the description carries the full burden. It does disclose a meaningful side effect (writing artifacts into the local cache) and describes the return shape (per-language counts, content fingerprint). It omits permissions/auth needs, idempotency/re-fetch behavior, and whether cache writes are destructive or additive.

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 action, zero filler. Every clause earns its place, including the return-value sentence.

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

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

For a tool with no annotations, no output schema, and 33% param coverage, the description covers purpose and returns but leaves parameter semantics and behavioral constraints (auth, caching, repeat calls) unaddressed. Adequate but with clear gaps.

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

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

Schema coverage is only 33% (just project_id documented), and the description adds no meaning for build_id or languages beyond the indirect hint of 'per-language file counts'. With low coverage the description should compensate, and it does not.

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 pair ('Download and extract') and resource ('a build's artifacts'), plus the downstream purpose ('so their files can be listed and read'). It indirectly distinguishes itself from octri_list_generated_files and octri_read_generated_file, though it never names 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?

The clause 'so their files can be listed and read' implies this is a prerequisite to the list/read siblings, which is real usage context. However, there are no explicit when-to-use/when-not statements, no prerequisites, and no sibling tools named outright.

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

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

No annotations exist, so the description carries the full behavioral burden. It usefully discloses the return content (per-language lifecycle phase, failure messages) and implies a read-only fetch, but says nothing about auth requirements, error behavior for a missing build, or whether the state is live or cached.

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 tightly packed sentence with the resource front-loaded and no filler; every clause carries information about what is returned.

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

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

With no output schema and no annotations, the description partially compensates by summarizing the returned state, but leaves the build_id parameter undocumented and offers no guidance on usage context or error conditions. Adequate but with clear gaps.

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

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

Schema coverage is only 50%: project_id is documented in the schema, but build_id is not, and the description explains neither. It does not clarify build_id's format or the project fallback behavior, so it fails to compensate for the coverage gap.

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

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

States a specific verb (retrieve) and resource (one build's current state) and enumerates the meaningful contents: each language's lifecycle phase and failure messages. This naturally contrasts with the plural octri_list_builds, though no sibling is named explicitly.

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

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

The description gives no when-to-use guidance, no prerequisites, and never points to alternatives such as octri_list_builds, octri_wait_for_build, or octri_diff_builds. An agent must infer the context entirely.

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 behavioral burden, and it discloses almost nothing. It does not say whether authentication is required, what happens when the slug does not exist, whether the project falls back to a default, or what the returned page contains.

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 short fragment with no wasted words and is trivially front-loaded, but it is terse to the point of under-specification rather than efficient communication.

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

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

For a tool with no annotations, no output schema, and an undocumented required parameter, the description should explain the lookup key, error behavior, and return shape. It supplies none of these, leaving the agent with substantial gaps before invoking it.

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

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

Schema description coverage is only 50%: project_id is documented in the schema but slug has no schema description, and the description only restates 'by slug' without adding format, casing, or resolution semantics. It does not compensate for the undocumented slug parameter.

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

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

The phrase 'One documentation page by slug' identifies the resource (a documentation page) and the lookup key (slug), which implicitly distinguishes it from the sibling octri_list_doc_pages. However, it is a sentence fragment with no verb and no explicit differentiation from the list tool, so the agent must infer that this returns a single page.

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 statement of when to use this tool versus octri_list_doc_pages or any other sibling, and no prerequisites or exclusions are given. Usage is only implied by the singular 'One documentation page'.

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

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

With no annotations, the description carries the full burden, and it does add real behavioral value by explaining the semantics of resolved=true (de-minified against an uploaded source map) and what its absence implies about missing symbols. It omits permissions, error behavior, and any read-only/safety context.

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

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

Two sentences, no filler, but the first is a sentence fragment and the semantic explanation of 'resolved' is placed before the core action is clearly stated, weakening front-loading.

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 and no annotations, so the description must carry the return-shape burden. It names the top-level payload and one field but leaves the structure of stack frames/events, pagination, and the required issue_id identifier unexplained, and the non-defaulted parameter is undocumented.

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 only 50%: project_id is documented in the schema but issue_id has no description anywhere. The description mentions no parameters at all, so it fails to compensate for the undocumented required issue_id.

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

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

The description identifies the resource ('one issue') and its payload ('stack frames and recent events'), which implicitly separates it from the sibling octri_list_issues. However, it is a verbless fragment ('One issue with...') rather than a clear statement of what the tool does, and it never explicitly names the retrieval action or contrasts with the list sibling.

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 when-to-use guidance is given. It does not state that this is the single-issue fetch to pair with octri_list_issues, nor any prerequisites or conditions under which to prefer it over alternatives.

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

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

With no annotations, the description carries the full burden; it usefully enumerates the returned contents and flags the revision dependency needed for write-back. However, it never states this is a read-only/no-side-effect operation or notes any permission requirements.

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

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

Two sentences, front-loaded with the resource and followed by the one actionable constraint (revision). No filler, though it could be slightly tighter.

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

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

No output schema exists, so the description does meaningful work by enumerating the returned fields and the revision's role. It is nearly complete for a simple single-parameter read tool, missing only safety/permission context.

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

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

Schema coverage is 100% and the single project_id parameter is fully documented in the schema, including its fallback behavior. The description adds no parameter detail beyond that, so the baseline 3 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 resource — persisted SDK Studio settings, per-endpoint overrides, revision, and last published release — so the agent knows exactly what is retrieved. It does not name the write counterpart octri_set_sdk_settings, though the mention of 'write settings back' alludes to it.

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 note that the revision 'is required to write settings back' suggests fetching this before a set operation, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative.

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 burden and does not meet it: it never says whether importing creates a new spec entry or overwrites an existing one, whether authentication is required, or what happens on failure. The only behavioral nugget is that the source must be publicly reachable, which is useful but far from sufficient 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?

A single front-loaded sentence with no filler — every word earns its place. It is terse to the point of under-specification, but that is a completeness problem rather than a conciseness one.

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 mutation tool with no annotations, no output schema, and one of two parameters undocumented, the agent lacks key information: does importing overwrite or add a spec, what identifies the resulting spec, and what is returned. The description is too thin for the tool's 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 50%: project_id documents its fallback-to-CLI-selected-project behavior, while url has no schema description at all. The description's 'public URL' phrase partially compensates by telling the agent the URL must be externally reachable, but gives no format or HTTP/HTTPS requirements.

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 (Import) and resource (an OpenAPI spec) plus the source constraint (from a public URL), which is enough to distinguish it from octri_push_spec and octri_validate_spec in the sibling list. It stops short of naming those siblings explicitly, so it falls just under the top band.

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 when-to-use or when-not-to-use guidance is given, even though octri_push_spec is an obvious near-neighbour that an agent could confuse it with. The agent is left to infer that this path is for remotely hosted specs versus locally supplied ones.

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 behavioral burden. It reveals only that builds are recent and include per-language status, with no mention of pagination, ordering, recency window, permissions, or other operational behavior.

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

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

It is a single, front-loaded sentence fragment with no wasted words. However, the extreme brevity leaves important details unstated rather than fully earning its place as a complete definition.

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 list tool with two optional parameters, no output schema, and no annotations, the description is incomplete. It omits pagination, ordering, scope, and any indication of what the per-language status values mean.

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 only 50%: project_id is documented in the schema, but page is not documented in either the schema or the description. The description adds no parameter semantics such as pagination behavior or how the CLI default project fallback works.

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 as SDK builds and narrows it to recent builds with per-language status, which is clearer than the tool name alone. It does not explicitly contrast itself with siblings such as get_build, diff_builds, or trigger_build.

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

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

The description provides no guidance on when to use this list tool versus alternatives like get_build or diff_builds. It also says nothing about prerequisites, scope, or exclusions.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about read-only semantics, pagination, ordering, or auth requirements. The only disclosure is that the pages are 'generated,' which is minimal 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?

One short, front-loaded sentence with no wasted words, but its brevity reflects under-specification rather than discipline. It is efficient but earns little.

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 list tool with no output schema, the description should indicate what is returned (e.g., page identifiers, titles) and any pagination behavior. None of this is present, leaving the agent unable to predict the response shape.

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%: the single optional project_id parameter is fully documented in the schema, including its fallback to the CLI's selected project. The description adds no parameter detail, so the baseline of 3 applies.

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

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

The phrase 'Documentation pages generated for the project' is a noun fragment that essentially restates the tool name (list_doc_pages) without a verb or explicit scope. It gives a vague hint about the resource but does nothing to distinguish this from siblings like octri_get_doc_page or octri_list_generated_files.

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

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

There is no statement of when to use this tool versus alternatives such as octri_get_doc_page (single page) or octri_list_generated_files. No context, prerequisites, or exclusions are offered.

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 the output content (files with sizes) and a hard dependency on a prior fetch, which is meaningful. It says nothing about read-only safety, pagination for large file lists, or what happens if the build+language was never fetched.

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 scope, followed by the prerequisite. No filler and nothing is buried.

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

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

For a simple list tool with no output schema and no annotations, the description covers the action, return content, and dependency. It omits list size limits, ordering, and failure behavior when the artifacts were not fetched, leaving gaps an agent would have to discover empirically.

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 only 33%: build_id and language have no schema descriptions. The phrase 'of a previously fetched build+language' does add real meaning — these two parameters must reference an already-fetched combination rather than arbitrary IDs — which partially compensates. project_id's fallback-to-selected-project semantics come from the schema, not the description.

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

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

States a specific verb and resource ('List the files') scoped to 'a previously fetched build+language' and notes the payload ('with sizes'). This distinguishes it naturally from octri_read_generated_file, yet it never names that sibling, so the differentiation is implicit rather than 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?

Gives an explicit sequencing precondition: 'Call octri_fetch_artifacts first.' That is a concrete when-to-use rule that most siblings lack. It stops short of naming when-not to use it or pointing to octri_read_generated_file for single-file retrieval.

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 ordering and grouping, which is useful, but says nothing about pagination, default limit/range, required permissions, or the shape of a returned issue beyond the presence of an id.

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, front-loaded sentences with zero filler. The ordering fact and the sibling linkage are both load-bearing.

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?

A five-parameter read tool with no output schema and no annotations needs more: defaults for limit/range, whether results are paginated, and what an issue record contains are all unstated. The description is too thin for the tool's surface area.

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 only 20% (only project_id is documented). The description adds no meaning for level, limit, range, or status; the enums provide allowed values but not semantics such as what 'ignored' means or how limit interacts with grouping.

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 resource is specific (grouped production errors) and the description states presentation order (newest first), making the tool's output recognizable. It also links forward to the sibling octri_get_issue, so an agent can distinguish the list tool from the detail 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?

Usage is only implied: the agent infers it should call this to discover issues and then use octri_get_issue for detail. There is no explicit when-to-use, when-not-to-use, or guidance on how the level/status/range filters change the result.

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 implies a read-only catalogue of languages plus their accepted preference keys, which gives the agent a sense of the return shape, but it never explicitly states that the operation is non-mutating, what auth it needs, or how the project fallback behaves.

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 compact sentence, front-loaded with the resource and its payload. No filler, though a slightly sharper verb would improve scannability.

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

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

For a simple read-only listing with one fully-described parameter and no output schema, the description is adequate but thin: it does not state the return format (list of language/key mappings) or how project selection affects results, leaving the agent to infer basic behavior.

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

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

Schema coverage is 100% and the single project_id parameter is documented in the schema ('falls back to the CLI's selected project'), so the baseline of 3 applies. The description adds nothing about project scope or how language results vary per project.

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

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

The description states a specific resource ('the SDK generator's language catalogue') and adds the useful detail that each language maps to preference keys. It is clear what the tool returns, though it never uses an explicit verb like 'list' or 'retrieve' and doesn't reference related tools such as get_sdk_settings.

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 call this tool versus alternatives. Since get_sdk_settings / set_sdk_settings deal with preferences, an agent would reasonably wonder whether language preference keys come from here or from those tools, and the description resolves nothing.

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 burden, and it discloses only provenance (the catalogue is derived from the SDK config). It says nothing about read-only safety, pagination, auth requirements, or what the response contains.

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 tight sentence with no filler, conveying the resource and its origin up front. It is well sized for a one-parameter read tool.

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

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

For a low-complexity, zero-required-parameter read tool with no output schema this is minimally adequate, but neither the return shape nor any usage context is described, leaving modest gaps.

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

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

Schema description coverage is 100% and the single optional project_id already documents its fallback-to-selected-project behavior, so the baseline is 3. The description adds no additional meaning about the parameter.

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

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

The description names a specific resource — the MCP tool catalogue published to the project's customers — which cleanly separates it from the other list_* siblings such as octri_list_specs, octri_list_operations and octri_list_languages. However, it is a noun phrase rather than a verb+resource statement, so the action (retrieve/list) is only implied.

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 statement of when to reach for this tool versus its many list_* siblings, nor any prerequisite or exclusion. The agent must infer usage purely from the resource name.

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 burden. It usefully discloses the return shape (method, path, operationId, deprecation) and implies a read-only enumeration, but says nothing about pagination, what happens when no spec exists in the project, or ordering.

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 with no filler; the resource and returned fields are front-loaded. The trailing clause 'the list the SDK Studio renders' adds context but is slightly ornate.

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-optional-param, no-annotation, no-output-schema tool, the description adequately names the returned fields, partly compensating for the absent output schema. It still omits empty-spec behavior and read-only confirmation, leaving a modest gap.

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

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

The single optional project_id is fully documented in the schema (100% coverage), including the CLI-selected-project fallback, so the schema does the heavy lifting. The description adds no parameter-level detail beyond that, which matches the baseline for high-coverage schemas.

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 resource (operations found in the current spec) and enumerates the returned fields (method, path, operationId, deprecation), so an agent knows exactly what this yields versus list_specs or list_builds. It is phrased as a noun clause rather than an explicit verb like 'List', but the resource 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?

There is no statement of when to reach for this tool rather than octri_list_specs, octri_validate_spec, or octri_list_doc_pages. Usage is only inferable from the resource name, and no prerequisites or exclusions 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?

No annotations are provided, so the description carries the full burden. It hints at return content ('with ids') but says nothing about permissions, whether the list is paginated, ordering, or completeness. For a tool with zero annotation coverage, this is thin.

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 no wasted words and the resource stated up front. It is arguably too terse, but nothing is padding.

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

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

With no output schema and no annotations, the description should do more to describe the shape and limits of the result. Mentioning ids is a small step, but pagination and authorization context are missing for a listing 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 100% and the single parameter already documents the optional project_id fallback behavior. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a clear verb (list) and resource (projects), scoped to 'the organisation', and notes that ids are included in the result. It does not differentiate itself from sibling listing tools like octri_list_specs, but 'projects' is a distinct resource an agent can recognize.

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

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

There is no when-to-use guidance, no mention of alternatives, and no stated prerequisites. The agent must infer from the name that this is the entry point for enumerating projects.

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 bears the full behavioral burden, yet it says nothing about read-only semantics, ordering, completeness of the list, pagination, or what happens when a project has no SDKs. The only added context is that repos are grouped per language and linked to SDKs.

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 fragment with no padding, and the key qualifier ('linked to the project's SDKs') is front-loaded. It is arguably under-specified rather than truly economical, but nothing is wasted.

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

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

For a simple one-parameter read tool with full schema coverage and no output schema, the description covers the essential what. However, with no annotations and no output schema, it should at least confirm this is a read-only listing and sketch the return shape, which it does not.

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 single optional parameter's fallback behavior is documented in the schema itself, so the baseline is 3. The description's phrase 'linked to the project's SDKs' hints at project scoping but adds no syntax or format detail 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 fragment names a specific resource — per-language GitHub repositories tied to the project's SDKs — which goes beyond restating the tool name and lets an agent distinguish it from siblings like octri_list_specs or octri_list_languages. It lacks an explicit verb, but the 'list' prefix plus the precise resource scope makes the intent clear.

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 statement of when to reach for this tool versus octri_list_generated_files, octri_fetch_artifacts, or other SDK-facing list tools, and no mention of prerequisites or the fallback-to-selected-project behavior beyond what the schema already says. Usage must be inferred entirely from the name.

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 only the ordering ('newest first'); it says nothing about result limits, pagination, whether the list is filtered by anything else, or what each entry contains. Ordering is a genuine behavioral detail, but it is the only one.

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 clause, front-loaded with the resource and the ordering. It is efficient, though it reads as a fragment rather than a complete statement of behavior.

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

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

With no annotations and no output schema, the description is the only source of behavioral context, and it omits return shape, pagination, and result limits for a listing tool. For a one-parameter read tool this is a meaningful gap.

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

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

Schema description coverage is 100% and the single project_id parameter is fully documented in the schema, including its fallback behavior. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

The description names the resource precisely (OpenAPI specs scoped to a project) and the ordering (newest first), which is enough to distinguish it from siblings like octri_validate_spec, octri_push_spec, or octri_import_spec_url. It lacks an explicit verb (list/retrieve), relying on the tool name to supply it, but 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?

There is no when-to-use guidance, no mention of when to prefer it over related spec tools, and no statement of prerequisites or the default-project fallback behavior. The agent must infer everything from the name and the sibling 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 provided, so the description carries the full behavioral burden. It hints that results are aggregated performance data (p50/p95), but says nothing about whether it is read-only, whether it requires an active deployment/time window, rate limits, pagination, or how absent data is handled.

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 tight sentence with the key metric front-loaded and no filler. It is efficient, though the extreme brevity is under-specification rather than a model of concise completeness.

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

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

With no annotations, no output schema, and only half the parameters described, the description is too thin for the tool's complexity. An agent cannot tell the default time range, the return shape, or how to disambiguate this from the other monitoring and query 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 coverage is only 50%: project_id is documented in the schema but the 'range' enum has no description anywhere. The description does not explain the default time window, the effect of omitting range, or the CLI fallback behavior for project_id, so it fails to compensate for the coverage gap.

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

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

The description names the data surfaced (slowest transactions with p50/p95 and suspected N+1 patterns) which is more informative than a bare name, but it is a noun phrase with no verb, so the action (retrieve/list) is only implied. It partially distinguishes from octri_monitoring_summary and octri_query_logs by naming its specific metric, but not explicitly.

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

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

There is no statement of when to use this tool versus siblings like octri_query_logs, octri_monitoring_summary, or octri_monitoring_releases, all of which could plausibly cover performance data. No prerequisites, no exclusions, no context beyond the implied 'for the project' scope.

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

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

With no annotations, the description carries the full burden, and it does disclose the return contents (error rate, new issues, regressions per release). It says nothing about default time windows, whether range falls back to a default, permissions, or pagination, so the behavioral picture is only partially filled in.

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 waste, with the reported metrics front-loaded and the usage cue second. Nothing is padded or redundant.

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 rightly sketches the returned metrics, and it identifies the resource. It leaves the range parameter and any default behavior unexplained, which for a two-parameter tool is a noticeable but not severe gap.

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

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

Schema description coverage is 50%: project_id documents its fallback behavior, but range is a bare enum with no explanation. The description adds no parameter-level guidance (e.g., default range or how windows are interpreted), so it does not compensate for the coverage gap.

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

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

The description names a concrete resource (releases) and the metrics it reports (error rate, new issues, regressions), so the agent can tell what the tool returns without opening the schema. It stops short of explicitly differentiating itself from siblings like octri_monitoring_summary or octri_monitoring_performance, which is why it isn't 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 second sentence ('how you tell whether a deploy made things worse') gives a clear use case, which implies when the tool is relevant. However, it names no alternative and gives no exclusions or preconditions, so the agent must infer how it relates to the other monitoring tools.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only summary and describes the metric payload, but never states that it is non-mutating, whether it requires project permissions, or how large/expensive the query is across long ranges like 90d. Adequate but incomplete for an annotation-free tool.

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

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

Three short sentences, zero filler, and the highest-value information (what metrics, then when to call) is front-loaded. 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?

For a simple two-parameter read summary with no output schema, the description usefully enumerates the returned metrics so the agent knows what it gets back. It omits project-scoping behavior (project_id vs CLI-selected project) and any cost/latency expectation for wide ranges, which keeps it short of a 5.

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

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

Schema description coverage is 100%, so both parameters (range enum with default 24h, optional project_id fallback) are already fully documented in the schema. The description's 'over a window' hints at the range parameter but adds no syntax, default, or scoping detail beyond the schema. Baseline 3 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?

Names a specific verb/resource combination ('Production health for the project') and enumerates the exact metrics returned (event count, error count, error rate, distinct issues) plus the scoping window. An agent can distinguish this from siblings like octri_list_issues or octri_monitoring_performance without opening any schema.

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

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

Gives explicit sequencing guidance: 'Call this before reading issues. It tells you whether there is anything to look at.' This is a clear use-context, though it does not state when-not to use it or name the alternative monitoring tools (octri_monitoring_releases, octri_monitoring_performance) that could be confused with it.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the key trait that no build is consumed and that the response is paths-only by default to keep it small, but it says nothing about permissions/auth, whether generation has side effects or writes anything to disk, or rate limits.

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 zero filler; the core capability and the cost-saving constraint are front-loaded, and the secondary use case ('fast loop') follows.

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, and the description does cover the return shape (file paths, optionally contents). For a 4-parameter, no-annotation tool it is nearly complete, but it omits whether previewed output persists or is discarded, which an agent would reasonably want to know.

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 four parameters (language, project_id, path_filter, include_content) are already documented in the schema. The description adds only a light echo of include_content ('optionally contents') and the single-language scope, which is the expected baseline when the schema does 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 states a specific verb (Generate) and resource (one language / the SDK output), plus what is returned (emitted file paths and optionally contents). The phrase 'WITHOUT spending a build' effectively separates it from octri_trigger_build, though it never names that sibling explicitly.

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

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

'This is the fast loop for generator changes' tells the agent the context in which to reach for this tool versus a full build. It does not name the alternative tool or state explicit exclusions (e.g. when a real build is still required).

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

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

With no annotations the description carries the full burden, and it does disclose the key behavioral fact that the upload becomes the 'new current spec' (i.e. it replaces the existing one) and that it returns a created spec id. However, it omits auth/permission needs, validation behavior on malformed specs, and error semantics for a mutation.

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

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

Two tight sentences with zero waste. The core action is front-loaded and the return-value note follows, which is valuable given there is no output 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?

For a mutation tool with no annotations and no output schema, the description covers the replace-the-current-spec effect and the return value, but leaves out permissions, validation failure modes, and any rollback/irreversibility note. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds only the JSON-or-YAML format hint for content and otherwise restates nothing beyond the schema, which is the correct baseline of 3.

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: uploads OpenAPI spec text as the project's new current spec. It clearly distinguishes itself from octri_import_spec_url by scope (raw text vs URL), though it does not name that sibling explicitly.

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

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

No when-to-use guidance, no prerequisites, and no mention of the alternative octri_import_spec_url or octri_validate_spec. The agent can infer you use this when holding local spec text, but nothing is stated.

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

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

With no annotations, the description carries the full burden, and it does disclose a real behavioral trait: results are raw and unaggregated (no dedup/grouping). It says nothing about retention window, ordering, default limit, or pagination behavior, which matter for a log query.

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 what the tool returns and followed by the selecting condition. No 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?

A 5-parameter tool with 40% schema coverage, no annotations, and no output schema needs the description to fill gaps on limits, time range semantics, and result shape; the description only covers purpose and one usage cue.

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 only 40% (only 'query' and 'project_id' documented), and the description adds no parameter meaning at all — level, limit, and range are left entirely unexplained. With low coverage the description needed to compensate and does not.

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 the resource concretely ('raw production events, unaggregated') and implicitly the action (query logs), and it differentiates itself from the grouped-view path an agent would otherwise reach for. It lacks an explicit verb, but the resource and scope are unambiguous.

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

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

It gives a clear trigger ('Use when an issue's grouped view is not enough') plus a concrete example ('every occurrence across releases'), which routes the agent away from grouped/aggregated alternatives. It stops short of naming the sibling tool (e.g. octri_get_issue) explicitly.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not mention truncation behavior despite max_bytes defaulting to 200000, what happens if the build is unfetched or the path does not exist, or whether content is returned as text or binary. For a zero-annotation read tool this is a thin disclosure.

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

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

Two short sentences, front-loaded with the action and resource. No padding, though the second sentence is more motivational than informative and could have carried the truncation or prerequisite detail instead.

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 5 parameters, no output schema, and no annotations, the description should carry more weight. It omits result-shape guidance (text vs. binary, truncation signaling via max_bytes) and any statement of preconditions, leaving the agent to guess at behavior for a tool whose siblings already cover listing and fetching.

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 60%: path, max_bytes, and project_id are documented in the schema while build_id and language are bare. The description adds that the build is 'fetched' (context for build_id) but does not clarify what values language accepts or the interaction with project_id fallback, so it only marginally compensates for the uncovered parameters.

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

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

States a specific verb and resource: 'Read one generated file from a fetched build.' The 'one generated file' phrasing implicitly distinguishes it from the sibling octri_list_generated_files, but the description never names that sibling or any other alternative, so the differentiation is inferential rather than 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 sentence 'This is how to inspect what the generator actually emitted' implies the use case (examining generator output) but gives no when-not guidance, no prerequisites (e.g. must a build already be fetched/available), and never routes the agent to octri_list_generated_files to discover paths first.

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. "In place" usefully signals that existing build state is mutated rather than a new build created, but it omits auth/permission requirements, what happens to already-succeeded languages, and how partial failures surface.

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 zero redundancy, and the in-place scoping plus the omit-to-retry rule are both 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?

For a 3-param mutation tool with no annotations and no output schema, the description covers the core behavior but leaves out side effects on prior successful artifacts and any permission prerequisites, which an agent would want before invoking it.

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

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

Schema coverage is only 33% (only project_id is documented in the schema). The description rescues `languages` semantics (named languages; omit to retry failures), but adds nothing about build_id, and project_id's fallback behavior is already in the schema.

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

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

States a specific verb+resource+scope: re-running selected languages of an existing build, in place. It is clearly distinguishable from octri_trigger_build (which creates a new build), though it never names that sibling explicitly.

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

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

Gives explicit conditional behavior: omit `languages` to retry only the failed ones. That tells the agent when the omission path applies, but it does not state when to prefer this tool over triggering a fresh build or diffing/validating instead.

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 behavioral burden. It is a mutation tool, yet the description never states permission requirements, whether changes are reversible, or how 'ignored' differs operationally from 'resolved' beyond the enum labels. The behavioral disclosure is essentially absent.

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 wasted words. It is efficient, though its brevity borders on under-specification for a mutation tool.

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 3-parameter mutation tool with no annotations and no output schema, the description conveys the action and outcomes but omits behavioral context and usage guidance. Adequate but with clear gaps.

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

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

Schema description coverage is 33%: project_id is documented but issue_id is not. The description partially compensates by interpreting the status enum in human terms (resolve, ignore, reopen), adding marginal value, but it leaves issue_id semantics to the plain type.

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

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

The description states a specific verb (triage/set status) and resource (issue), and enumerates the three outcomes (resolve, ignore, reopen as `unresolved`). This distinguishes it from read-only siblings like octri_list_issues and octri_get_issue, though it does not name a sibling by name.

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

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

The phrase 'Triage an issue' implies the context of use, but there is no explicit when/when-not guidance or mention of alternatives. Usage is left to inference from the sibling set.

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

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

With no annotations, the description carries the full burden and does well: it discloses that settings are replaced wholesale rather than merged and that stale revisions are rejected (optimistic concurrency). It stops short of covering auth/permission needs or what the call returns.

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

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

Three short sentences, all front-loaded with the action and the critical read-modify-write constraint. No filler; every clause carries operational information.

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

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

For a mutation tool with no annotations and no output schema, the description covers the essential contract: full replacement, required revision, and stale-revision rejection. Minor gaps remain around error/return behavior and the role of optional fields like version and changelog.

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 80%, so the baseline is 3, but the description adds real meaning beyond the schema by clarifying that 'settings' must be a complete object (read-modify-write) and that 'revision' is the value previously read, not an arbitrary number.

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 ('Write SDK Studio settings') and implicitly distinguishes itself from its read counterpart by naming octri_get_sdk_settings as the prerequisite step. An agent can immediately tell this is the write side of the get/set pair.

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

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

Explicitly prescribes the workflow: read first with octri_get_sdk_settings, modify, then pass the full object plus the revision. It also states the failure condition ('A stale revision is rejected'), so the agent knows the concurrency contract before calling.

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 burden. It usefully discloses the non-blocking async contract and the two follow-up patterns, which is genuinely valuable. However, it says nothing about permissions/auth, failure behavior on invalid language ids, or that this creates a persistent build resource.

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, then the return behavior and next steps. No filler; 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?

For a simple trigger tool with no output schema and no annotations, the description covers the essential contract: what it queues, that it returns immediately with a build id, and how to follow up. Lacking only permission and error-handling context.

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

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

Schema coverage is 67%; languages and project_id already have schema descriptions, and the description's 'one or more languages' reinforces the array's multi-value nature. The version parameter is undocumented in both schema and description, leaving a real 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 (queue) and resource (SDK build) with clear scope (one or more languages). It also differentiates itself from sibling tools by naming octri_get_build and octri_wait_for_build as the consumption paths.

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

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

Explicitly describes the async workflow: it returns immediately and tells the agent to either poll with octri_get_build or block with octri_wait_for_build, effectively an alternative-selection rule. It does not address when to prefer this over other trigger-like siblings (e.g. octri_retry_build) or any preconditions, so it falls short of a full 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses cost ('cheap') and sequencing relative to builds, but not whether validation is read-only, whether it can fail with errors, or what form the result takes.

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 waste, with the core action front-loaded and the cost/sequencing rationale immediately following.

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-required-parameter tool this is nearly sufficient, but with no output schema the agent cannot know whether the validator returns a pass/fail, a list of issues, or a raw error — a gap the description does not fill.

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%, and the sole parameter (project_id) is fully documented in the schema. The description adds no extra meaning for the parameter, so the baseline 3 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?

Specific verb+resource: 'Run the generator's validator against the project's current spec.' An agent can tell this apart from build-oriented siblings like octri_trigger_build or octri_preview_sdk, though it never explicitly names a sibling.

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?

'Cheap; do this before spending a build' gives a clear trigger condition and positions the tool in a pre-build workflow. No explicit when-not or alternative named, but the guidance is actionable.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the key blocking trait, but omits what happens on timeout (error vs. partial result) and any permission/rate considerations, leaving real gaps for a long-running blocking call.

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, zero waste, and the blocking behavior is front-loaded ahead of the usage hint. Nothing to trim.

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

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

With no annotations and no output schema, the description does describe the return ('final per-language result'), but leaves the timeout/blocking semantics and failure behavior unexplained for a tool whose whole point is waiting.

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 67% and the description adds no parameter detail at all; build_id carries no schema description but is self-evident from its name. project_id and timeout_seconds are already documented in the schema, so the description neither helps nor harms.

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: 'Block until every language of a build reaches a terminal state, then return the final per-language result.' An agent can tell this waits rather than polling, though it does not explicitly contrast with the sibling octri_get_build.

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?

'Use after octri_trigger_build' names the sequencing alternative clearly. No when-not guidance (e.g. don't call when you already have a finished build_id), so it stops short of full 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?

No annotations are present, so the description carries the full burden. It implies a safe, read-only identity check and that the returned project reflects session state, but it never states that the call has no side effects, what happens when no project is selected, or any auth/permission requirements. 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?

Two compact sentences, front-loaded with what the tool returns before the call-to-action. Every clause carries information; nothing is padding.

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

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

With no output schema and no annotations, the description usefully enumerates the returned fields, which is what an agent needs to decide whether to call it. It falls slightly short on edge-case behavior (empty project selection, failure modes), but is close to complete for a tool this simple.

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% and the single optional project_id is fully documented in the schema, including the CLI-selected fallback, so the baseline of 3 applies. The description's phrase 'currently selected project' loosely echoes the fallback behavior but adds no new syntax or override 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 enumerates exactly what is returned — user, org, plan, API URL, selected project — which is specific enough to distinguish it from siblings like octri_list_projects or octri_get_sdk_settings. It is less a verb+resource statement than a return-value inventory, and it does not explicitly contrast itself with any sibling, so it stops short of 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?

'Call this first to confirm which environment the session is pointed at' gives a clear, actionable directive on when to invoke it. It does not name an alternative or state when not to use it, but for a session-introspection tool the positive guidance is strong.

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