codeDB Lens

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

The description explicitly says the tool is 'read-only' but also says it 'Saves the report in the profile's history.' Persisting a report to history is a write-like side effect, which contradicts the readOnlyHint=true annotation.

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

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

The description is a single, front-loaded sentence that efficiently packs runtime, output contents, and persistence behavior. It is dense but not wasteful.

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

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

Given that an output schema exists, the description need not explain return values. It covers runtime and the main result categories, though it omits explicit sibling selection guidance and leaves the read-only/history-save tension 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 coverage is 100%, so both parameters are already documented. The description mentions operating 'on a profile' but adds no syntax, format, or constraint details beyond the schema.

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

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

The description states a specific verb and resource: 'Run the codeDB Lens health check on a profile.' The output summary (A-F grade, findings, rules without data) further distinguishes it from siblings such as query, compare, or list_rules.

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 implies use when a profile-level health check is wanted and gives runtime expectations, but it gives no explicit when-not-to-use guidance and does not mention alternatives like compare, describe_table, or explain_rule.

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; the description adds genuinely non-structured context — the auth/key requirement and the default pair of runs. It still doesn't clarify what happens if fewer than two runs exist or whether runs must be from the same profile, which are the practical failure modes for a diff 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?

One sentence front-loads the operation and its output, followed by the default and the auth prerequisite. No filler, no repetition of the name, and every clause carries information the agent needs.

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

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

With an output schema present, the description need not explain return values, and it covers defaults and the key requirement. The only gap is edge-case behavior — what happens with fewer than two runs or mismatched run origins — which keeps it from being fully complete.

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

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

Schema coverage is 100%, with a/b already documented as older/newer run paths and profile pointing at list_profiles. The description's 'two latest defaults' reinforces the a/b ordering but adds no syntax, format, or constraint detail beyond the schema, so 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 verb (compare) and resource (two runs of the same instance), and even names what the result contains: new, resolved and persisting findings plus grade change. That output framing separates it cleanly from siblings like history (which lists runs) and get_finding (which retrieves one).

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

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

Gives a concrete default (the two latest runs) and an explicit prerequisite (the user's free key via codedb-lens register), so an agent knows how to call it with minimal input. It does not name alternatives or say when not to use it, e.g. when the user only needs a single run's findings.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description additionally signals that row counts are 'estimated' (i.e. catalog statistics, potentially approximate). Beyond that it does not describe freshness of the metadata, cost, or failure behavior for non-existent tables, and much of its return-content detail overlaps 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?

Two sentences with no filler. The return inventory is front-loaded and the usage note follows economically, though leading with a noun phrase rather than a verb makes the opening marginally less scannable.

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 explain return values, yet it still previews them, and it covers the when-to-use. Combined with 100% parameter coverage and read-only annotations, an agent has essentially everything needed to call it 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%: 'table' documents the schema.name/default-schema form, 'profile' points to list_profiles, and 'database' documents its default. The description adds no parameter meaning beyond this, 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?

It enumerates the concrete resource of the operation — 'one table or view' — and lists the returned artifacts (columns with type/nullable/default, primary key, foreign keys with referenced table, indexes, estimated rows), which makes the scope unambiguous. It stops short of naming a sibling (e.g. list_tables) to contrast with, so it is clear but not differentiating.

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 it before writing a query, so column names are right' gives a concrete triggering situation rather than vague advice. There are no explicit exclusions or named alternatives, but the preparatory framing is enough to place it relative to query and list_tables.

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

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

Annotations already declare readOnlyHint=true, so safety is covered and the description's job is lighter. The description usefully discloses the payload (measured metric, rationale, next action, verification, required permission, SQL, doc link), but says nothing about cost, latency, or failure behavior when the rule_id is unknown/invalid. Note the annotation pair readOnlyHint=true with idempotentHint=false is internally odd, though the description does not contradict it.

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

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

One front-loaded sentence with a colon-delimited list of what the explanation returns; every item earns its place and there is no preamble. It is dense but tightly structured.

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

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

With an output schema present, the description need not describe return values, yet it still previews the explanation's contents, which helps an agent decide whether to call it. Params are fully documented in schema and safety is covered by annotations, leaving only minor gaps like error behavior and a prerequisite pointer.

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 rule_id parameter already carries an example format ('MSSQL-BACKUP-001 or PG-AUTOVAC-001'). The description adds nothing about the parameter, so 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 opens with a specific verb+resource ('Explain one rule') and enumerates exactly what the explanation covers, so an agent can tell it apart from list_rules or get_finding. It never explicitly names a sibling, so it stops short of a 5.

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

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

Usage is only implied: the singular 'one rule' plus a required rule_id suggests a per-rule deep dive after list_rules has produced an ID. There is no explicit when-to-use statement, no stated prerequisite (e.g. obtain the ID from list_rules or get_finding), and no mention of alternatives such as check or get_finding.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=false. The description adds useful behavioral context by specifying the returned contents: status, impact, next action, verification guidance, and all evidence rows.

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 tightly written sentences with no wasted words. The core scope is front-loaded, and the default-run note is placed efficiently at the end.

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

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

The tool has an output schema, full parameter documentation, and safety annotations, so the description does not need to explain return formats or permissions. It is nearly complete, though it could better clarify its relationship to explain_rule and list_rules.

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 profile, rule_id, and run are already documented in the schema. The description reinforces the default-run behavior but does not add substantial parameter semantics 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 retrieval action and resource: full detail of one rule in a saved run. The scope distinguishes it from list-oriented siblings such as list_rules and from run-level tools like history.

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

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

The description implies usage by saying it returns detail for one rule in a saved run and defaults to the latest run. However, it does not explicitly say when to use this instead of explain_rule, check, or list_rules.

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

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

Annotations already establish this as a read-only operation, and the description adds helpful context about ordering (newest first), returned fields, and downstream tool compatibility. It does not explain why idempotentHint is false or address pagination beyond what the schema already states.

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 definition is two compact sentences with no wasted wording. The core purpose and ordering are front-loaded, followed by a useful downstream routing note.

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 tool with full schema coverage, an output schema, and clear annotations, the description is complete enough to call it correctly. It covers what the tool returns and how results can be used downstream.

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 are well documented in the schema. The description reinforces that results are tied to a profile and ordered newest first, but it adds no additional parameter syntax or constraint details beyond the schema.

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

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

The description clearly identifies the resource: saved check runs of a profile, including the data fields and ordering. It implicitly distinguishes itself from the live-check sibling by saying 'saved' check runs, but it does not explicitly name an alternative tool for selection.

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 provides useful follow-up guidance by noting that each run's path can be passed to get_finding or compare. However, it does not say when to use history instead of check, list_profiles, or other siblings, so usage selection is only implied.

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

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

Annotations already establish read-only behavior. The description adds meaningful context by clarifying that results are limited to databases the profile's login can open and by indicating the visible attributes such as state and size, which helps explain the access-scoped result set. It does not cover ordering, pagination, or performance traits.

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 carefully constructed sentence front-loads the resource and scope, then lists the returned fields. There is no wasted text.

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 and full parameter schema coverage, the description does not need to explain return formatting. It covers the access scope and content of the listing, though it could be more complete by mentioning when to choose this over sibling list 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 100%, and the single profile parameter already documents that it comes from list_profiles. The description adds no further parameter guidance, so the schema does the heavy lifting and the baseline of 3 is appropriate.

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

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

States a specific list action on databases and adds useful scoping detail: only databases this profile's login can open, plus the fields returned. It does not explicitly contrast with siblings such as list_tables, but the resource is clear enough to distinguish 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 description implies use when an agent needs available databases for a profile, especially since the required profile parameter references list_profiles. However, it never states when to prefer this over list_tables or other list tools, nor any exclusions or prerequisites beyond the schema.

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 read-only profile, but the description adds real value beyond them: it discloses the security guarantee that passwords and connection strings are never returned, and 'you may use' signals that results are permission-filtered to the caller. It does not mention ordering or whether the list is cached, which would have earned 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?

A single sentence with the capability front-loaded and the safety caveat trailing. Every clause earns its place; the enumerated fields are the only mild redundancy given an output schema exists.

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 is present and the tool takes no parameters, so the description's job is limited to orienting the agent — which it does, including scope and the data-exclusion guarantee. Nothing needed to call this 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate — baseline 4 applies. Note the description instead spends its words on the return shape, which is technically the output schema's job rather than parameter semantics.

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

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

States a specific verb ('List') and a precisely scoped resource ('saved connection profiles'), then enumerates the returned attributes (name, engine, host, initial database, language). 'Connection profiles' is clearly distinct from sibling resources like list_databases, list_tables, and list_rules, so an agent can route without opening a 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?

Usage is implied — an agent reads this to discover which connections are available before querying — but the description never states when to prefer it over list_databases or other siblings, nor any prerequisites or exclusions. Adequate but leaves the selection decision to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known; the description adds real value beyond that with the sampling cadence (every 15 s for 1 or 24 h) and the return ordering (newest first), both of which affect how results should be interpreted. It stops short of disclosing volume or pagination behavior for large profiles.

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 with the core resource and scope front-loaded and the fallback tool mentioned second. Every clause carries information; there is no filler or restated boilerplate.

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 explain return values, and it covers the key behavioral facts an agent needs: read-only access, sampling granularity, ordering, and the alternate route for external recordings. Only pagination or volume expectations are left unaddressed, which is a minor gap for a single optional parameter 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 coverage is 100% and the only parameter's description already explains that an empty value lists recordings of every profile the caller may use. The description reiterates the profile-scoped framing but adds no syntax, format, or edge-case 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 clearly identifies the resource (recordings kept with a profile's reports) and its scope, including the sampling characteristics and ordering (newest first). It distinguishes itself from recording_report by noting that tool handles recordings made elsewhere, but the listing verb itself is only implied by the tool name rather than stated.

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

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

It explicitly names recording_report as the alternative path for recordings made elsewhere, giving the agent a concrete routing condition. It does not address when not to use this tool broadly (e.g., other listing tools like list_profiles or history), but the key sibling relationship is covered.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds domain semantics about rule kinds, but says nothing about result size, pagination, or how the catalog is scoped.

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 is listed and what comes back. The rule-kind sentence is compact and meaningful rather than 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?

With an output schema covering return shape, annotations covering safety, and full parameter documentation in the schema, the description supplies enough for an agent to call it correctly. Only the absence of sibling routing keeps it from full marks.

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 engine parameter is already documented as "mssql or pg; empty lists both". The description adds no filtering detail beyond the schema, so 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 verb and resource ("List the Lens rule catalog (health checks)") and enumerates returned fields (ID, engine, category, severity, title). It distinguishes itself from action-oriented siblings like check/explain_rule only implicitly through the noun "catalog"; no sibling is named.

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

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

Usage is implied: this is the enumeration endpoint, and the note that "series" rules judge recordings while others run in a check hints at downstream workflow. It never says when to use this instead of explain_rule or get_finding, and gives no prerequisites 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?

Beyond the readOnlyHint=true annotation, the description discloses the important scoping constraint that results are limited to what the profile's login can see, and that readability per table is reported. It omits pagination/row-limit behavior, which is the main remaining unknown for a listing 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?

Two compact sentences, front-loaded with the resource and returned fields, followed by the workflow hint. No filler and nothing repeated from the schema.

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

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

An output schema exists, so return values need no prose explanation, and annotations cover safety. Combined with the workflow hint and the login-scoping caveat, an agent has everything needed to call 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 100%, so filter, schema, profile, and database are already fully documented in the schema. The description adds only the concept of login-scoped visibility filtering, not per-parameter semantics; 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 and resource ('list_tables') and then enumerates exactly what each row contains (schema, name, type, estimated rows, size, read permission), which no sibling offers. An agent can distinguish it from describe_table, list_databases, and query without opening a 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?

The sentence 'Start here, then describe_table, then query' is an explicit workflow that names two alternatives and the order in which to use them. This is the strongest form of routing guidance: it says when to use this tool and what to use next.

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?

Beyond the readOnlyHint annotation, the description discloses the row limit (500 unless changed), 2 KB cell limit, truncated flag semantics, refusal of multi-statement and side-effecting SQL, keyword-quoting guidance, and uncommitted-read behavior. These are substantial behavioral details an agent needs before calling the 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?

The description is front-loaded with the core action, then adds operational guidance and limits in dense but purposeful sentences. Almost every sentence adds a constraint, caveat, or usage rule rather than restating the 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?

Given that annotations mark the tool read-only and an output schema exists, the description covers the critical gaps: SQL restrictions, row/cell truncation, profile row limits, and dirty-read behavior. It is complete enough for an agent to invoke query correctly without needing to inspect sibling 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 100%, so the schema already documents all five parameters. The description still adds useful meaning by giving the concrete default row limit of 500 unless the user changed it, explaining truncated results, and clarifying that sql must be a single SELECT or WITH ... SELECT.

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: run one read-only SELECT (or WITH ... SELECT) on a profile and return columns and rows. This clearly separates it from sibling tools such as list_tables, describe_table, compare, or record_command, which do not execute arbitrary read-only SQL.

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 actionable usage guidance: aggregate in SQL with GROUP BY or TOP/LIMIT instead of fetching raw rows, and it explains that writes, EXEC, multiple statements, and side-effecting functions are refused. It does not explicitly route the agent to list_tables/describe_table for schema inspection, so it is clear but not exhaustive.

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?

The readOnlyHint=true annotation is consistent with a tool that only returns a command string, and the description usefully adds the 1 h / 24 h-with-free-key limit as behavioral context. However, it does not explain what the returned command string looks like or how it relates to the eventual list_recordings/recording_report flow, so the added context is modest against annotations that already signal a harmless read.

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

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

Two short sentences with zero filler, and the key behavioral rule ('you cannot start a recording') is front-loaded ahead of the instruction to the agent. Nothing could be removed without losing meaning.

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 explain return values, but for a two-step workflow tool it omits the follow-on context an agent needs: what to tell the user after running the command, and how this pairs with recording_report or list_recordings. The essentials are there, but the workflow context is thin.

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 both parameters (profile, duration) are fully documented in the schema, and the description reinforces the duration limit (1 h default, 24 h with the free key) and that the profile name comes from list_profiles. It adds reinforcing meaning to the duration constraint rather than pure duplication, but offers nothing beyond what the schema states.

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 resolves the ambiguity in the name 'record_command' by stating it returns the command string the user runs in a terminal, not an executed recording. It clearly distinguishes the tool's output (a command) from the act of recording, though it doesn't explicitly contrast with siblings like list_recordings or recording_report.

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?

'You cannot start a recording: give the user this command' is an explicit usage constraint that tells the agent both when to use it and what to do with the result. It stops short of naming an alternative tool for the actual recording flow, but the context 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?

The description says the tool 'also writes the HTML report into the recording folder', which is a filesystem side effect, while annotations declare readOnlyHint=true – a direct inconsistency that the agent should be aware of. To its credit the description does disclose the write (and that idempotentHint=false follows, since repeated runs rewrite the report), but the conflict with the annotation prevents a higher score.

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 dense sentence, front-loaded with the core verb and resource, followed by an enumerated payload list and the report-write note. Slightly run-on, but every clause carries information an agent would otherwise have to infer.

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 three-parameter analysis tool with a 100%-covered schema and an output schema, the description is close to complete: it names the findings categories, the chart peaks, the top queries, and the report artifact. The only missing piece is any note about error conditions or behavior on an empty/partial recording.

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 would be 3, but 'optionally for a period (e.g. an incident)' adds meaning beyond the schema: it clarifies that from/to define an incident window and are optional, which the RFC 3339 descriptions alone do not convey. The folder parameter's provenance is already handled 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 and resource ('Analyse a recording') and then enumerates exactly what the analysis produces: time coverage, gaps, episodes, chart peaks, top queries. No sibling tool (list_recordings, compare, query) could be confused with this, and the agent knows the scope before 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?

'Optionally for a period (e.g. an incident)' hints at the scoping use case, but there is no explicit when-to-use versus list_recordings, compare, or query, and no stated prerequisites (e.g. that a recording must first be identified). Usage is implied rather than prescribed.

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