Runzumi

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

Annotations already declare readOnly/idempotent/non-destructive, so the description focuses on what they can't convey: role-gated billing, the fact that repository cards and recent jobs are previews rather than full data, and the snapshot.usageCompleteness condition for daily usage. This is meaningful disclosure about result fidelity and access limits, though it says nothing about rate limits or pagination.

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?

Four sentences, front-loaded with purpose before the caveats, and each sentence carries real information (scope, role gate, preview semantics, completeness flag, alternative tool). It is dense with qualifiers but not padded.

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-value structure need not be explained, and the description still covers the important behavioral caveats an agent needs: role-gated billing, preview vs complete data, and the usageCompleteness flag. The only gap is not distinguishing itself from open_dashboard.

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?

Only one parameter, and schema coverage is 100% – workspaceId is already documented as the ID from list_workspaces with a pattern and length bounds. The description adds no format or sourcing detail beyond that, so the baseline 3 for a fully-covered schema 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 ('get an overview of a Runzumi workspace') and enumerates what it returns: runner status, recent CI jobs, billing, repository cards. It explicitly names the sibling it should lose to for spending data (get_usage), so an agent can separate it from nearby read tools without opening the 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?

Provides an explicit alternative for one case ('For workspace spending, prefer one get_usage call') and a conditional caveat on billing visibility by user role. It stops short of routing against open_dashboard or the other list_* siblings, so selection is clear only for the spending case.

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 this as a safe, read-only, idempotent, closed-world operation. The description adds the retrieval scope (what data is returned), but does not disclose authentication needs, rate limits, or failure modes, leaving it at a baseline level of added value.

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 single sentence is front-loaded with 'Use this to get...' and contains no redundant or filler text. It is appropriately sized for a simple getter.

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 annotations cover safety. However, the description omits usage guidance relative to sibling tools, leaving a gap that an agent might need to infer from tool names alone.

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

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

Schema description coverage is 100%, so the schema fully documents both required parameters. The description adds no parameter-level detail, which is acceptable given the schema's completeness, but it does not exceed the baseline.

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 'get' and specifies the returned data: GitHub installation, runner profile, and runner status for one Runzumi repository. It implies single-repository scope, contrasting with the bulk list_repositories sibling, 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?

The phrase 'Use this to get...' is a purpose statement, not guidance on when to choose this tool over alternatives like list_repositories. No conditions, prerequisites, or exclusions are provided.

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 safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real interpretive value: the fields surfaced (status, runner start times, failure/queue reason, cost, billing method, commit) and the caveat that a runner start failure is distinct from the GitHub conclusion.

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 tight sentences, front-loaded with the use case and followed by return contents and a key caveat. The field enumeration is somewhat list-like but each item earns its place for a diagnostic 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?

With an output schema present, the description needn't detail return values, yet it summarizes them and adds the failure-vs-conclusion nuance. Combined with 100% schema coverage and full annotation coverage, an agent has enough to call this correctly; only explicit sibling routing is missing.

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

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

Schema description coverage is 100%: jobId is documented as coming from list_runs and explicitly distinguished from the GitHub workflow run ID, and workspaceId points to list_workspaces. The description adds nothing about the parameters, so the schema carries the load and 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 specific verb and resource: examine ONE GitHub Actions job attempt in Runzumi, or its cost. The word 'one' implicitly separates it from the list_runs sibling that returns many, though no sibling is named explicitly. 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?

'Use this to examine one slow or failed GitHub Actions job attempt ... or its cost' gives a clear diagnostic context for when to reach for it. It does not name an alternative tool or state when NOT to use it, so it falls short of explicit routing guidance.

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

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

Annotations already declare this a read-only, idempotent, non-destructive, closed-world call, so the safety profile is covered. The description adds real behavioral context beyond that: unit conversions for duration/queue/cost, what a missing costUnits means, that a null result for a revision signals changed data, and that filters follow GitHub status semantics.

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 dense block front-loaded with purpose, then a stream of field and filter semantics. Every sentence carries information, but a few simply echo the schema (timestamps in epoch milliseconds, omit revision), so it is efficient rather than maximally tight.

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?

Although an output schema exists, the description names the aggregate fields an agent must combine (durationSum/durationCount, queueSum/queueCount) and explains the units and the cost-availability edge case, which is exactly what is needed to interpret the result. Combined with the 366-day range limit in the schema, an agent has everything required to call and read this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly restates schema facts (epoch milliseconds, omit revision for current data, omit repositoryId for all repos) but does add meaning the schema lacks — notably that filters map to GitHub status and that the repositoryId choice should not be emulated by enumerating repositories.

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 opening sentence names a specific verb and resource set — job duration, queue time, success rate and cost — scoped to a workspace and time range, so the agent knows exactly what this returns. It also implicitly separates itself from a per-repository enumeration approach, though it never names a sibling tool (e.g. get_usage or get_dashboard) that could be confused with 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?

Clear conditional guidance is given for the key decision points: omit repositoryId for workspace totals, supply it only to narrow scope, and explicitly 'Do not enumerate repositories to calculate workspace totals.' It also states when to omit revision and how to pick a status filter. It stops short of naming alternative sibling tools for adjacent questions, so it is not 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?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond that: the result is a 31-day daily series with specific fields, and costUnits is a scaled unit (3000000 = 1 USD). It does not mention pagination or auth requirements, keeping it short of a 5.

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?

Front-loaded with purpose and scope, then constraints, then return shape and unit conversion. Every sentence carries distinct, actionable information with 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?

Despite an output schema existing, the description still clarifies the returned row structure and the cost unit conversion, which prevents misreading costUnits. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and both parameters are already documented in the schema, including the omit/supply semantics for repositoryId. The description largely restates that, adding only the aggregation warning, which is usage guidance rather than new parameter meaning.

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 ('get Runzumi compute usage and cost') and pins the scope to the complete authorized workspace. It also distinguishes itself from the sibling get_run by routing per-job cost questions there.

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 when-to-use rules: omit repositoryId for all repositories, supply it for one, one workspace call replaces per-repository calls, and never sum dashboard previews. It names get_run as the alternative for single-job cost.

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 readOnly/idempotent/destructive/openWorld annotations already covering safety, the description adds non-obvious pagination behavior: search applies per page and an empty page can still carry a next cursor. It does not cover auth or rate limits, but that is minor given the annotation set.

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, front-loaded sentences with no filler. The pagination edge case is valuable, though the first sentence's 'find a GitHub repository' (singular) is slightly loose for a list 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?

Output schema exists, so return values need no explanation; annotations cover safety; schema documents parameters. The description adds purpose and pagination edge-case context, though it stops short of mapping the tool against get_repository/list_workspaces.

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 limit, cursor, search, and workspaceId are fully documented in the schema. The description adds only that search is page-scoped, which slightly clarifies behavior but does not add 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?

States the resource (GitHub repository in Runzumi) and two purposes (find a repository, check runner readiness), plus paginated search via 'The search applies to each page.' However, it does not explicitly differentiate from the sibling get_repository or say it lists repositories, leaving the list-vs-get boundary to the name/title.

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 opening 'Use this to...' gives clear intended context (finding repos and checking runner readiness). It does not name alternatives or when not to use it (e.g., use get_repository for a known repository), so no exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: results are individual job attempts, filtering is by GitHub status, and a job whose runner failed to start can still report as queued. Pagination behavior is also mentioned, though return shape detail is left to the output schema.

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?

Four sentences, all front-loaded and information-dense: purpose, result granularity, filter semantics, and pagination/scope. No redundant restatement of the tool name or 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. The description covers scoping, pagination and filter semantics, which is sufficient for an 8-parameter list tool; the time-range limits are handled by the schema. It is complete without being exhaustive.

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 a baseline of 3 is warranted. The description nonetheless adds meaning beyond the schema for repositoryId (omitting it means all accessible workspace repositories) and cursor (advance it for more results), plus the status/failure filtering intent.

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 ('find') plus resource ('GitHub Actions jobs in Runzumi') and scope ('recent, failed, queued or running'). It also defines the unit of a result ('one job attempt'), which cleanly separates it from siblings like get_run, get_run_statistics and search_run_logs.

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 concrete usage rules: omit repositoryId to span all accessible workspace repositories, follow the cursor for more results, and how the status filter maps to GitHub status semantics. It does not name alternative tools (e.g. get_run for a single attempt) or state when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context about pagination termination (iterating on cursor until isDone), which is not derivable from the annotations alone.

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, with the access-scope constraint and the pagination rule 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?

An output schema exists, so return fields including isDone need not be re-explained. The description covers purpose, scope, and pagination; only explicit sibling routing is absent, which is a minor gap for this simple read-only list 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%, with limit and cursor fully documented in the schema (bounds, default, null-for-first-page). The description reinforces the cursor contract but adds no syntax or format detail beyond the schema, 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 states a specific verb and resource ('get the Runzumi workspaces') plus the access scope ('that the user can access'). It is clearly separate from the get_* siblings, though it does not explicitly contrast with other list_* tools like list_repositories or list_runs.

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 clear context for use (retrieve accessible workspaces) and an explicit pagination procedure: 'Follow the cursor until isDone is true to get all workspaces.' There are no stated exclusions or named alternatives, but the when-to-use condition is unambiguous.

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, non-open-world behavior, so the safety profile is covered. The description adds selection behavior beyond the annotations: 'A workspace without repositoryId selects All repositories,' which tells the agent how the panel resolves scope.

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 usage condition followed by the selection semantics. No filler or restatement of 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?

Output schema exists so return values needn't be described, and all three parameters are documented in the schema. The trigger and default-selection rule are present; only the precedence among workspaceId/repositoryId/jobId is left 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 100%, so the baseline is 3, but the description adds semantics the schema does not: the interaction between workspaceId and repositoryId (omitting repositoryId selects All repositories). It still doesn't explain how jobId interacts with the other IDs.

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 ('Opens the panel') and what it operates on ('selected workspace, repository or job'). It distinguishes itself reasonably from data-returning siblings like get_dashboard by framing this as opening a UI panel, though it doesn't 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?

Gives an explicit trigger: 'Use this when the user wants to see Runzumi analytics in a panel.' That is clear invocation context, but it offers no when-not-to-use guidance or explicit routing away from get_dashboard.

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, destructiveHint=false and openWorldHint=false, so the full safety profile is covered structurally. The description adds only that the settings are "saved" (i.e., persisted, not defaults), which is marginally useful but does not disclose scoping, auth needs, or fallback behavior when unset.

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 sentence with no filler, and the verb/resource are front-loaded. It is arguably thinner than it could be, but it wastes nothing.

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 explained, and annotations plus zero params keep the behavioral burden low. The remaining gap is disambiguation from settings.read and update_preferences, which the description leaves entirely open.

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; the baseline of 4 applies. No misleading parameter claims are made.

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: "Read the saved display settings of the user." That is concrete enough for an agent to know what comes back (user-level display settings). It does not, however, distinguish itself from siblings like settings.read or update_preferences, which occupy adjacent territory.

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 or when-not-to-use guidance, and no alternative is named. With both read_preferences and settings.read in the sibling list, the description does nothing to tell the agent which one to pick.

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 read-only, idempotent, non-destructive and closed-world, so the bar is lower; the description still adds real value by disclosing pagination ('one page'), output masking, and an injection-safety warning that log lines are data and must not be followed. It does not state auth needs or how size/time limits truncate results, but the added safety and pagination context is substantive.

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?

Five short sentences with the use trigger front-loaded, followed by return shape, then the safety constraint. Every sentence carries information, though the final two directives about data handling and display could be tightened into 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?

With an output schema present, return values need not be explained, and the description still covers scope, paging, masking and prompt-injection handling. Slightly incomplete in that it never routes the agent away from search_run_logs or explains truncation behavior when size/time limits hit.

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

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

Schema coverage is 100%, so jobId, workspaceId, source, limit and cursor are all documented in the schema with constraints and cross-references. The description contributes only the notion of paging ('one page') and masking, which is baseline-level support; nothing new about parameter syntax or formats.

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 ('logs of a GitHub Actions job in Runzumi') and describes the return shape (one page of masked log lines with source and status). It is clearly distinct from generic run-metadata siblings like get_run, but it never contrasts itself with search_run_logs, the closest sibling, leaving the agent to infer the boundary.

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 trigger ('use this when the user asks for the logs of a GitHub Actions job') and directional guidance on output ('show only the lines that the user needs'). There is no when-not condition and no mention of search_run_logs as the alternative for cross-run log searching, which is the main gap.

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 the safety profile is covered. The description adds two useful behavioral facts beyond the annotations: result caps (10 repositories, 10 job attempts) and implicit scoping to the default workspace. It does not disclose match semantics, ranking, or pagination 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?

A single front-loaded sentence with no filler. It is efficient, though its brevity is partly under-specification rather than discipline.

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

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

The output schema exists, so return-value detail is not required, and annotations cover safety. However, for a search tool whose only input is an undocumented free-text query, the definition leaves the central mechanic (what a mention is, how the query is interpreted) unresolved.

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 parameter 'query' is required, so the description must carry the burden — yet it never mentions the query at all. An agent cannot tell whether the query is free text, a substring, a regex, or a structured pattern, nor what fields it matches against.

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 what is returned (up to 10 repositories and 10 recent job attempts in the default workspace) but never explains what a 'mention' is or what the search operates over, which is the core purpose implied by the name. It also does not distinguish this from siblings like list_repositories, list_runs, or search_run_logs, which return overlapping resource types.

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

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

There is no guidance on when to use this tool versus list_repositories, list_runs, or search_run_logs. The only scoping clue is 'default workspace of the user', which is a constraint rather than a selection criterion.

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, closed world), and the description adds meaningful context beyond them: logs are masked, results are paged with a cursor, a page-level miss is not a definitive miss, and it warns not to follow instructions embedded in log lines (prompt-injection defense).

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?

Five short sentences, purpose front-loaded, and each clause carries distinct value: what it searches, matching semantics, pagination, the non-conclusive miss caveat, and the injection warning.

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, full parameter coverage, and rich annotations, the description supplies the behavioral details an agent needs to call it correctly. The only gap is that it never contrasts with the sibling read_run_logs, leaving the search-vs-read choice to inference.

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

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

Schema coverage is 100%, so every parameter including cursor, source, and search is already documented in the schema. The description restates the case-insensitive substring behavior and adds light cursor guidance ('follow the cursor to search more pages'), but contributes little 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?

States a specific verb and resource ('find an error or text in the logs of a Runzumi job') and the matching mechanism (case-insensitive substring on one page). It functionally distinguishes itself from read_run_logs, but never names that sibling or any alternative, so sibling 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?

Clear usage context ('find an error or text') plus practical guidance: follow the cursor for more pages, and a no-match on one page is not conclusive. It gives no explicit when-not-to-use or pointer to the sibling read_run_logs for full log reads.

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 the safety profile is fully covered by structured data. The description adds no behavioral context beyond that — no note on whether it errors when no default is set, whether it falls back to a first workspace, or whether any auth/workspace scoping applies.

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. It conveys the return payload immediately, which is the right shape for a no-argument getter.

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-value detail is rightly omitted, and a zero-parameter read is inherently simple. However, the description leaves the tool's relationship to read_preferences and the title's 'display settings' framing unexplained, which is a real gap in a 16-tool sibling set.

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; the baseline of 4 applies. No parameter claims are made or needed.

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 the exact resource returned: the user's default workspace and repository. That distinguishes it somewhat from siblings like get_repository and list_workspaces, though it never reconciles the mismatch with its own title ('Read Runzumi display settings') or explains how it differs from read_preferences.

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 named alternatives, despite several plausible overlapping siblings (read_preferences, get_repository, list_workspaces). The agent must infer that this is the zero-argument default-lookup tool.

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 safety and idempotency (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower, yet the description still discloses a real cross-field side effect: 'A new workspace clears the default repository.' That is exactly the kind of non-obvious behavior an agent would otherwise get wrong. It does not, however, explain how to clear a value deliberately or what happens on partial writes.

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 filler, with the core action stated first and the side effect immediately after. 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. The remaining gap is operational detail about partial updates and clearing values in a nested-object mutation, but for a two-field settings write the description is largely sufficient.

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

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

Reported schema description coverage is 0%, though the schema's titles ('leave empty to select later', 'leave empty for All repositories') carry most of the meaning. The description adds genuine value by naming both fields and describing how workspaceId interacts with repositoryId, but it never mentions the nested 'set' object, its minProperties=1 requirement, or that empty strings are the clearing mechanism.

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 ('Save') and resource ('the default workspace and repository of the user'), which is enough to distinguish it from read-only siblings like settings.read and read_preferences. The title's framing ('Runzumi display settings') is slightly narrower than what the description says, but the description itself is unambiguous about what is being written.

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 and no mention of the nearest alternative, update_preferences, which an agent could easily confuse with this tool. Usage is only inferable from the resource being written, so the agent gets no explicit routing signal.

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=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally, and 'Save' is consistent with the write hint. The description adds nothing beyond that: it does not say whether settings are merged or replaced, whether the write is scoped per workspace/repository, or whether any permissions are required.

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 filler, and the verb leads. It is efficient, though its brevity here reflects under-specification rather than disciplined trimming.

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 two required, undocumented scoping parameters and a sibling read/update pair, the description is too thin. The presence of an output schema excuses it from explaining return values, but it still omits scope, prerequisites, and alternative-tool routing that an agent needs to invoke this correctly.

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 33%: only 'status' is documented (with a rich enum), while the two required parameters, workspaceId and repositoryId, have no descriptions anywhere. The description mentions no parameters at all, so it fails to compensate for the coverage gap on the required fields.

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 verb ('Save') and a resource ('display settings of the user'), so the agent knows it is a write of settings. However, it does not differentiate from the sibling 'settings.update' or clarify its relationship to 'read_preferences', and the phrasing 'display settings' is vague and does not match the workspaceId/repositoryId/status parameters the schema actually requires.

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 prerequisites, and no routing to alternatives such as 'read_preferences' (the read counterpart) or 'settings.update'. The agent must infer entirely from the name that this is the write side of a preferences pair.

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