Summer

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that approval is a separate team decision, clarifying that this tool does not itself approve the request, but it provides no further behavioral detail (e.g., whose request is read, return shape). Given annotation coverage, this added context is modest but useful.

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 core action, and every sentence carries weight: the first states the operation, the second disambiguates approval scope. No filler or redundancy.

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

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

For a zero-parameter, read-only tool with rich annotations and no output schema, the description covers purpose and the key caveat that approval is out of scope. A minor gap remains: 'the person's' is ambiguous (likely the caller's own request given no parameters and a summer_account_me sibling), and the description does not clarify this.

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?

There are zero parameters, so the baseline for parameter semantics is 4. The description correctly adds no parameter details because none are needed, and the schema trivially documents the empty object.

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 ('Read') and resource ('person's Summer access request'), making the tool's purpose immediately clear. However, it does not explicitly name or differentiate itself from the sibling tool summer_account_access_request_submit, so it falls short of the highest bar for sibling differentiation.

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: read the access request. The second sentence ('Approval is a separate Summer team decision') gives a when-not hint by clarifying that this tool does not handle approval, but it does not name an alternative tool or state explicit conditions for choosing this over the submit sibling. This is implied usage rather than explicit guidance.

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

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

Annotations already declare non-read-only, open-world, non-idempotent and destructive behavior, so the safety profile is largely covered. The description adds the useful scope note that it cannot approve, but says nothing about what an update overwrites or what the request returns, so it does not fully exploit the lower bar.

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 no wasted words. It is efficient, though arguably terse for a destructive 3-param mutation, keeping it just shy of a 5.

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 a mutation tool with destructiveHint and no output schema, the description covers purpose and scope but omits update-vs-create semantics and field expectations. Together with annotations this is minimally adequate but leaves real 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 only 33% (just idempotency_key) and the description mentions no parameters at all, so it fails to compensate for the undocumented company_name and note fields. The names are somewhat self-describing but the description adds zero semantic value over 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 (submit/update) and resource (Summer access request), and the second sentence scopes it by excluding approval. It clearly contrasts in spirit with the 'access_request_read' sibling, but never names it explicitly, so it stops short of a full 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?

'This cannot approve access' implies a boundary (use another tool to approve), which is a partial when-not signal. However there is no explicit when-to-use statement, no prerequisites, and no named alternative, so guidance 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds one useful behavioral detail (that the result marks inclusion status per company), but nothing about scoping, refresh, 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?

A single front-loaded sentence with no filler. It is effectively a verbatim copy of the title, so it is tight but adds no phrasing of its own.

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

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

For a zero-parameter, read-only list tool with full annotation coverage and no output schema, the description conveys what is returned (companies plus per-connection inclusion). It omits any note on result shape or pagination, but that is minor at this complexity.

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

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

The tool takes zero parameters and the schema has additionalProperties=false with 100% coverage, so there is no parameter semantics for the description to explain. Baseline 4 applies.

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

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

States a specific verb (List) and resource (companies the person can access) plus a scope qualifier (whether this connection includes each one). It is clear enough to distinguish from most siblings, though it never explicitly contrasts with the close sibling summer_account_connections_list.

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

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

No when-to-use or when-not-to-use guidance and no named alternatives. The agent can infer a list operation from the verb, but nothing routes it between this tool and connections_list or the company_* 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the useful fact that the response includes grants, last use and expiry — worthwhile since there is no output schema — but says nothing about pagination, auth requirements, or what an empty result means.

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 nothing extraneous, front-loaded with the verb and resource. It is efficient, though it mirrors the title rather than adding new 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?

With no output schema, the mention of returned fields (grants, last use, expiry) partially compensates. But for a read tool in a family that also revokes connections, it omits sibling routing, pagination behavior, and any caveat about whose connections are listed — leaving real gaps even against the rich annotation 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 and the schema is empty, so there is nothing for the description to clarify; the baseline for parameter-free tools applies. No misleading parameter semantics are introduced.

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 verb and resource ('List this person's agent connections') and names the data returned (grants, last use, expiry), so the purpose is discernible. However, it is a verbatim restatement of the title and adds no differentiation from siblings such as summer_account_connections_revoke or summer_account_me. 'This person' is also ambiguous with no parameter to identify the person.

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 prerequisite, and no mention of the alternative tools in the same family (e.g. summer_account_connections_revoke for revoking access, summer_account_me for profile data). Usage can only be inferred from the tool 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?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description only adds 'immediately' and 'this person's', without explaining consequences such as whether the agent loses access instantly, whether revocation is reversible, or what happens to the connection's credentials.

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 and free of filler. However, it is essentially a restatement of the title and could have used its brevity to include a crucial detail such as irreversibility.

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

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

This is a destructive mutation with no output schema and low parameter coverage. The description lacks key facts an agent needs, such as what happens after revocation, whether it can be undone, and what the 'connection' parameter identifies.

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%. The description does not explain what the 'connection' UUID represents, when to supply 'reason', or how 'idempotency_key' should be used. The schema itself only describes idempotency_key, leaving the description with a gap it does not fill.

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 (revoke) and resource (agent connection), so the action is clear. However, it does not differentiate from sibling tools such as summer_account_connections_list or clarify which 'person' scope is involved.

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?

Offers no guidance on when to revoke a connection versus viewing it, what prerequisites exist, or what alternatives are available. The word 'immediately' hints at urgency but does not define usage conditions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds modest value by enumerating what the call surfaces (person, access status, connection grant), but says nothing about auth requirements, rate limits, or freshness of the access status. With annotations carrying the safety burden, a 3 is appropriate.

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, and the three returned items are listed compactly. It is essentially the title repeated verbatim, which is efficient but adds no new framing.

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

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

For a zero-parameter, read-only introspection tool with full annotation coverage and no output schema, the description gives an agent enough to call it correctly and know roughly what to expect. Only the absence of usage context keeps it short of complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a parameterless schema is 4, and no misleading parameter hints are present.

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 pairs the verb "Show" with three concrete resources (signed-in person, Summer access status, connection grant), which is specific enough for an agent to understand what comes back. It does not, however, name or contrast any sibling such as summer_account_connections_list or summer_company_settings_read, so sibling differentiation is left to inference.

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

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

There is no when-to-use guidance, no stated prerequisites, and no mention of alternatives among the many account/company read tools. The identity-scoped nature of a "me" endpoint is only implied by the name, not stated in the description.

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 destructiveHint=true and idempotentHint=false; the description adds the useful clarification that the action only queues work for human approval and performs no execution. It does not explain what state changes occur, what happens on retry with the same idempotency key, or whether repeated calls create duplicate approval requests.

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 the second sentence is a meaningful boundary statement rather than filler. Nothing could be removed without losing 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 5-parameter mutation with no output schema, the description covers intent and the non-execution boundary but omits what is returned (approval request identifier/status) and the preconditions for a valid plan. Annotations carry the safety profile, so the gap is moderate rather than severe.

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?

No parameter is mentioned in the description. With only 60% schema coverage, 'case' and 'plan_request_id' carry no descriptions anywhere, and the relationship between the case and the plan being prepared is left to inference. The phrase 'current saved plan' is only a weak signal toward plan_request_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?

States a concrete verb ('Prepare') and resource ('the exact work in the current saved plan'), which is more specific than a bare name restatement. It does not differentiate itself from sibling tools, but no sibling covers the action/session domain, so the risk of confusion is low. 'Prepare' itself remains somewhat abstract about what artifact is produced.

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 'Does not approve or execute' implies this is a pre-step in an approve/execute workflow, but no alternative tool is named and no prerequisites (e.g., a plan must already exist and be saved, where plan_request_id comes from) are stated. Usage is inferable rather than explicit.

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=true, so the safety profile is covered. The description adds one genuinely useful behavioral fact: the review records are truncated to the latest 20, which tells the agent the return is bounded rather than paginated. It says nothing about required authorization or scoping beyond what the schema implies.

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 or redundancy - the payload contents come after the verb+resource, which is the right order. It is penalized only because it duplicates the title word-for-word rather than using its one sentence to add 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?

With no output schema, the description must describe the return, and it does name the four returned elements, which is adequate for a read-only get. However, it omits what happens when the capability does not exist, whether the 20 review records are paginable, and how company/environment scope the lookup - gaps that matter for a tool whose whole purpose is fetching a composite record.

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 67%: company and environment carry descriptions, but the required 'capability' identifier (with its ^[a-z][a-z0-9_]{1,79}$ pattern) is undocumented. The description adds no parameter meaning at all, not even clarifying that the capability slug is the same key used by the sibling list/report tools, 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 (Read) and a specific resource (one capability) and even enumerates the payload it returns: the concrete test, evidence, and latest 20 review records. It is clear what the tool does, but it does not distinguish itself from siblings like summer_capability_checks_list, _report, _save or _test, and the sentence is a verbatim restatement of the 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?

There is no when-to-use guidance, no prerequisites, and no routing to alternatives, even though the sibling set contains four other capability-check tools (list, report, save, test) that an agent must choose between. The agent can infer it is the singular-read counterpart to the list tool, but the description never says so.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds almost nothing beyond that: no pagination, ordering, result-size or filtering behavior, and the closing sentence 'Every usable API, browser or knowledge path can count' is too ambiguous to convey a behavioral rule.

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 no padding, so size is fine. However, the second sentence is cryptic and the first leads with 'Read the same ... shown in Summer', which front-loads a UI comparison rather than the operation itself.

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, the description must carry the return-shape burden; it does partially enumerate what comes back (checklist, results, discovery paths, review history). It omits pagination, ordering, and any empty-result behavior, which matters for a list endpoint scoped by company and environment.

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

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

Schema description coverage is 100% (both company and environment are documented, with an enum on environment), so the baseline is 3. The description adds no meaning about how company or environment scope the returned checks, so it neither helps nor hurts.

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 (operational capability checklist, results, discovery paths, review history) but never states the action as a listing operation or scopes it to a company/environment. It does not distinguish itself from the sibling summer_capability_checks_get, so an agent cannot tell why it would call this one rather than fetch a single check.

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 exclusions, and no mention of the sibling tools (get, report, save, test) that cover adjacent operations. The phrase 'the same ... shown in Summer' implies UI parity but gives no selection criteria.

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 annotations (which already flag this as a destructive, non-idempotent, open-world write), the description adds genuinely useful behavioral context: the record is labeled as agent-reported and is 'never human approval or independently verified execution.' That provenance guardrail is something no annotation conveys. It does not explain the destructive/overwrite behavior or the version-conflict handling, so it stops 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?

Three tight sentences, front-loaded with the action and its payload, followed by the validation rule and the provenance caveat. No filler, though the opening sentence largely restates the title verbatim.

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

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

This is a complex tool: 9 parameters, 7 required, a nested object, enums, and no output schema, yet the description ignores the optimistic-concurrency contract (expected_version) and the idempotency_key retry semantics documented only in the schema. For a mutation with this much surface area, the description leaves important calling behavior unexplained.

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 44% across 9 parameters, so the description must carry more of the load than it does. It only touches 'evidence' and 'discovery' (via the pass requirement), saying nothing about company, environment, capability, expected_version, state, notes or the fulfillment.kind enum.

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

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

The description names a specific verb ('Record') and resource (the setup agent's capability assessment), plus the two payload elements that matter (evidence and discovery path). It is clear on its own, but never explicitly distinguishes itself from the very similar sibling summer_capability_checks_save, leaving the agent to guess which of the two writing tools to call.

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 versus summer_capability_checks_save, _get, _list or _test. The only guidance is an internal validation rule ('A pass needs evidence and a discovery path'), which constrains the payload rather than telling the agent when this tool is the right choice.

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 destructiveHint=true and openWorldHint=true, but the description adds real context beyond them: 'Resets its result and retains history' tells the agent state is destroyed yet auditable, and the final sentence clarifies the operation's blast radius. It omits any mention of idempotency_key semantics even though an idempotency_key parameter exists.

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, front-loaded with the action and followed by the state-effects and boundary caveats. Each sentence carries information, though the reasoning behind 'custom_' prefixing could be slightly clearer.

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 destructive, open-world write tool with no output schema and a nested definition object, the description covers state semantics but leaves out what a caller receives back after the reset, how expected_version conflicts are surfaced, and when to reuse idempotency_key. Adequate but not complete for a mutation of this complexity.

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

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

Schema coverage is 57%, and the schema self-documents company, environment, expected_version and idempotency_key. The description contributes only indirectly, implying the notes field is a required 'reason' and that the new capability must carry a 'custom_' prefix — a naming convention not stated anywhere in the schema. The nested definition object's seven fields get no description-level explanation.

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 action pair (edit an expectation / add a custom_ capability), identifies the resource, and adds a scope qualifier that rules out adjacent operations. It is clear against siblings like summer_capability_checks_get/list/test, though it never names one 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 negative guidance ('Does not create a provider tool or grant execution access') usefully bounds what this is not, but there is no positive when-to-use statement, no mention of when to prefer this over summer_capability_checks_test or _report, and no concurrency/version-conflict guidance despite expected_version being 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?

The description explicitly calls the operation 'read-only' and says it does not execute changes, while annotations declare readOnlyHint=false and destructiveHint=true. This directly contradicts the structured safety profile an agent relies on, and no other behavioral details (state touched, side effects, retry behavior) are offered.

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, front-loaded with purpose followed by prerequisites and exclusions; no filler. The mild cost is that sentence one duplicates the title rather than extending it.

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 six-parameter tool with an idempotency key, an optimistic-concurrency expected_version, and no output schema, the description leaves the mechanics of the call entirely to the schema. Combined with the read-only framing against destructive annotations, an agent cannot form a correct expectation of what the call does.

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?

Six parameters with only 67% schema description coverage, and the description names none of them. 'Authorized sample case' obliquely gestures at case_id and 'current runtime access' vaguely at expected_version, but capability, company, environment, and idempotency_key get no added meaning anywhere in the prose.

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 first sentence states a concrete verb and resource (request a capability test) scoped to an authorized sample case, which distinguishes it from sibling capability_checks_get/list/report/save. It is, however, an almost verbatim restatement of the title, so it adds little beyond what the title already conveys.

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 prerequisite-binding hint ('needs investigations.request and current runtime access') and a boundary ('does not approve or execute customer changes'), which is implicit when-not guidance. It never routes the agent between this tool and siblings like summer_verification_run, summer_actions_prepare, or summer_capability_checks_report.

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 annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the safety profile is covered. The description adds the key behavioral trait that the download is 'short-lived', which is useful context not present in annotations, though other details like expiration window or permission requirements are 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?

The description is a single front-loaded sentence with no wasted words. However, its conciseness comes at the cost of under-specification, as it merely duplicates the title rather than adding actionable detail.

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

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

With no output schema and 4 required parameters, the description should clarify what the 'short-lived download' returns (e.g., a URL and expiry) and how to obtain the case/attachment IDs. It omits these essentials, leaving the agent under-informed for even a simple read operation.

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% (company and environment have descriptions; case and attachment do not). The description mentions 'attachment' and 'case' relationally but does not explain their formats or how to obtain valid UUIDs, leaving the gap unaddressed for half the 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?

The description is a verbatim restatement of the tool title, so it adds no information beyond what the title already conveys. While the title itself is clear, the description fails to independently state a specific verb and resource in a way that distinguishes this tool from siblings.

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

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

No when-to-use guidance, no exclusions, and no alternatives are mentioned. An agent must infer that this tool is for downloading attachments, but receives no help on selecting it over related tools like summer_cases_get.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds a modest hint about return content ('original messages and related records'), but omits pagination behavior implied by 'after' and any note about how much related data is returned.

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, and the scoping detail ('one', 'original messages') is placed where it is read first. It is efficient, though arguably too terse to be fully useful.

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 read-only tool whose annotations cover the safety profile and with no output schema, the description is passable but leaves the pagination parameter unexplained and does not distinguish this getter from its list/attachment siblings.

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

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

Schema description coverage is only 50%: company and environment are documented, but case and after are not, and the description adds no meaning for any parameter. Notably, 'after' looks like a pagination cursor for messages, and nothing in the description explains it, so the coverage gap is not compensated.

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 (Read) and resource (one case or conversation) and clarifies the scope as singular with messages and related records, which implicitly separates it from summer_cases_list. However, it is nearly a verbatim restatement of the tool title and names no sibling explicitly, so an agent gets little help disambiguating it from summer_cases_attachment or summer_cases_list.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the alternative tools (summer_cases_list for enumeration, summer_cases_attachment for attachments). The agent must infer usage from the name alone.

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, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are newest-first, pagination is cursor-based, and text search is unsupported — the last point prevents a plausible misuse.

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

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

Two short sentences, zero filler, with the core behavior front-loaded and the API limitation appended as a caveat. Every clause carries 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?

There is no output schema, so the description must carry return-value context; it hints at 'coverage' and a cursor but never explains what coverage means or what the page envelope looks like. With 5 parameters, 2 required, and low schema coverage, the definition is usable but leaves real gaps for correct invocation.

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

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

Schema description coverage is only 40%: limit, cursor and status carry no descriptions, and only company/environment are documented. The description mentions the cursor exists but adds no meaning for limit, status values, or cursor format, 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 (list) and resource (company-owned cases/conversations), plus ordering (newest first) and return shape hints (coverage, cursor). It is distinguishable from summer_cases_get and summer_messenger_conversations_assistant, though the phrase 'cases or conversations' leaves some ambiguity about which entity is actually returned.

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 and no named alternative among the many sibling list tools (e.g. summer_events_list, summer_investigations_list). The only constraint given is a negative one — 'Text search is not available through the API yet' — which tells the agent what cannot be done but not when this tool is the right choice.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description's only added behavioral content is that unavailable items come with a reason, which is a minor return-shape hint. With no output schema, the description should say more about what the response looks like and any access requirements, which it does not.

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 or redundancy. It is efficient, though the brevity reflects under-specification rather than disciplined conciseness.

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 two required scoping parameters (a company UUID and an environment enum), the description is too thin: it does not mention the company/environment scoping, what the returned capability list looks like, or what 'unavailable' means operationally. An agent can only guess at the shape of the call and the response.

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% — the company UUID and the staging/production enum are both documented in the schema. The description adds no semantics beyond that, so the baseline 3 applies. It notably never mentions that the result is scoped to a specific company and environment.

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 conveys that the tool enumerates what capabilities are available for a connection and gives reasons for anything unavailable, which is a workable statement of purpose. However, it is essentially the title verbatim, contains no explicit verb+resource framing, and does nothing to distinguish it from siblings such as summer_capability_checks_list, summer_capability_checks_get, or summer_company_setup_status. It is vague on what 'connection' and 'here' refer to.

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

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

There is no guidance about when to call this tool versus the many capability/status siblings (summer_capability_checks_*, summer_company_setup_status, summer_company_settings_read). No preconditions, no mention of what happens when a capability is unavailable, and no exclusions. The agent must infer usage 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety behavior is covered. The description adds scope context ('company-wide settings,' 'every environment'), but does not describe return format, pagination, or other read-specific behavior. With rich annotations, this is 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?

The description is short and front-loads the read purpose. However, the second sentence, 'Changes affect every environment,' is ambiguous for a read-only tool and arguably does not earn its place in a description of what the tool itself does. Still, it avoids verbosity.

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 tool with rich annotations and full schema coverage, the description is largely complete. It conveys purpose and scope, and no output schema exists, so return-value detail is not strictly required. It could better distinguish itself from summer_company_settings_update, but the essentials are present.

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 'company' parameter is already documented in the schema as 'Summer company ID.' The description adds no parameter-specific syntax, format, or constraint information. Baseline 3 is appropriate when the schema fully carries 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?

The description states a specific verb and resource: 'Read company-wide settings.' This clearly distinguishes it from write-oriented siblings such as summer_company_settings_update, though it does not explicitly name that sibling. The added scope note, 'Changes affect every environment,' clarifies the settings' scope but is not needed for basic purpose identification.

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 explicit when-to-use or when-not-to-use guidance. It does not mention the related update tool or any conditions under which reading company-wide settings is appropriate versus alternative read tools. Usage must be inferred from the tool name and description.

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 destructiveHint=true, openWorldHint=true, and readOnlyHint=false, so the mutation risk is covered structurally. The description adds one genuinely useful piece of context — that the change affects every environment — but says nothing about what settings get overwritten, permission requirements, or how the optimistic-concurrency 'expected version' check behaves on conflict.

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 no filler. It is efficient, though the first sentence duplicates the title verbatim, which slightly reduces the value of the space used.

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 seven-parameter, six-required destructive mutation with no output schema and 43% schema coverage, the description is far too thin. It omits the meaning of most required fields, the consequence of the version mismatch, and any recovery/idempotency guidance despite an idempotency_key parameter being present.

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 43%, so the description must compensate, and it does not. It nods at 'expected version' (matching the already-documented expected_version) but leaves name, note, company, timezone, and workflow wholly unexplained, including no clarification that six of seven params are required.

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 ('Update company-wide settings'), which is clearly distinguishable from the sibling summer_company_settings_read. However, the sentence essentially restates the title and never explicitly names the read counterpart as the alternative.

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

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

No guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The only contextual remark ('Affects every environment') is a blast-radius warning rather than usage 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety behavior is fully covered elsewhere. The description adds only an enumeration of possible state values, without saying what a 'setup item' is, how freshness or caching behaves, or what triggers a state change.

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 short, but the single sentence is duplicated word-for-word from the title, so no sentence earns its place. Brevity here reflects 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 read-only status tool with no output schema and 100% schema coverage, the description is technically the only place to explain what 'setup items' and the returned states mean, and it omits that entirely. An agent cannot tell what is being reported or how to interpret the states.

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

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

Schema description coverage is 100% for both parameters (company UUID, environment enum), so the schema carries the full burden. The description contributes nothing about parameter meaning, making the baseline 3 appropriate.

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

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

The description is a verbatim restatement of the tool's own title, listing the state values rather than stating an action. It never says the tool retrieves or returns status for setup items, so the agent must infer the verb from the name alone.

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 versus siblings such as summer_company_settings_read, summer_company_capabilities, or summer_capability_checks_get. No context, 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The second sentence hints that mutation of roles/invitations is out of scope, but it is ambiguous ('stay in Summer') and adds little concrete behavioral context such as pagination, ordering, or how pending invites are represented.

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

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

Two short sentences with the primary purpose front-loaded and no wasted words. The trailing sentence is slightly cryptic, which keeps it from a 5, but the structure is efficient.

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 read-only list tool with full annotation coverage and no output schema, the description covers the essential scope. It could say a bit more about what the returned member/invitation records contain, but nothing critical to correct invocation 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 the single 'company' UUID parameter is fully documented in the schema. The description adds no format, constraint, or semantics beyond that, 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?

States a specific verb and resource: 'List company members and pending invitations.' The scope (members + pending invites) is more precise than the sibling 'summer_account_companies_list', but the description never names a sibling or explicitly distinguishes the two, so it falls 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?

'Role changes and invitations stay in Summer' implies a boundary (this tool reads; mutations happen elsewhere), which is weak when-to-use guidance. No alternative tool is named and no prerequisites (e.g., required permissions or company context) are given, so usage 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description's 'Never returns values' adds genuinely useful security context beyond those hints, but says nothing about ordering, pagination, or what it does when no credentials exist.

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 very short sentences, front-loaded with the core action and immediately followed by the most important constraint. Every word earns its place; nothing is 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?

With only two required, fully documented parameters, no nested objects, no output schema, and complete annotation coverage, the description needs little more. The one real gap is that it never clarifies ordering, scoping behavior per environment, or relationship to the set/rotate counterpart.

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

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

Schema description coverage is 100% – both 'company' (Summer company ID, UUID format) and 'environment' (staging/production enum) are documented in the schema itself. The description adds no parameter-level meaning 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?

The description states a specific verb and resource ('List saved credential names, sources and versions') and adds a scoping qualifier ('Never returns values') that tells an agent exactly what data it will and will not get back. It implicitly separates itself from the write counterpart summer_credentials_set, but it never explicitly names or routes to 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as summer_credentials_set for storing or rotating credentials. The only usable signal is the 'Never returns values' note, which hints at a discovery/inspection use case but is not framed as 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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful output behavior ('Returns metadata only', 'Returns a local CLI command when a secret is involved'), which tells the agent no secret material comes back. There is mild tension, though: the description implies set does not replace active credentials, while destructiveHint=true and the required expected_version suggest an in-place update path — the description understates that.

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 short sentences, front-loaded with the action, then the exclusion rule, then the two return-shape facts. No filler and nothing 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?

With no output schema, the description correctly covers the return shape (metadata only, CLI handoff for secrets), so the agent knows what comes back. It does not mention the optimistic-concurrency role of expected_version or the retry semantics of idempotency_key, but the schema documents both, so the gap is minor.

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 86% and the schema itself explains source semantics, secret_name applicability and idempotency_key reuse, so the schema carries the load. The description adds no parameter-level detail beyond what the enum descriptions already say, which is the expected baseline here.

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 — saving a single credential value or Doppler reference — and the word 'one' implies no bulk write, which separates it from a listing tool like summer_credentials_list. It does not explicitly contrast itself with the sibling set as a whole, 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?

Explicitly routes the agent away for the replacement case: 'Replacing an active credential needs credentials.replace.' That is a real when-not rule. However, that referenced tool is not present in the sibling list, and there is no guidance on when to pick source=doppler versus source=local_value beyond the schema's own enum description.

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, openWorld and non-destructive, so the safety profile is fully covered. The description adds cursor-based pagination and the resume mechanism, which annotations do not convey, but it omits ordering, rate limits, and what the events represent.

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 that are front-loaded with the purpose, and the resume hint earns its place as operational guidance. It is slightly terse to the point of being cryptic about next_cursor's origin, but 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 no output schema, the description should explain the returned event stream and pagination fields, but it only alludes to next_cursor. For a simple read/list tool with full annotation coverage this is minimally adequate, not 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 50% (company and environment are documented; after and limit are not). The description gestures at the cursor concept underlying the 'after' parameter but says nothing about 'limit' bounds or its effect, so it only partially compensates for the coverage gap and lands on 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 names a specific verb (Read) and resource (configuration and activity events) plus the mechanism (after a cursor), so the agent knows exactly what it retrieves. No sibling deals in events, so there is little to differentiate against, which is why this sits at a clear-but-not-sibling-scoped 4.

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?

'Resume from next_cursor' implies the pagination pattern, but there is no explicit when-to-use, when-not-to-use, or alternative tool guidance. The agent is left to infer that this is a forward-scanning list call with no stated conditions for choosing 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them by disclosing 'Never returns values', which tells the agent that credential values are redacted and only metadata/required-field structure comes back — a meaningful operational constraint.

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, and the most load-bearing fact for an agent's expectations — that no values are returned — is placed prominently. Nothing is repeated from the title 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?

With no output schema, the description does carry return-value burden, and it discharges the critical part by stating that no values are returned. It stops short of describing the shape of the returned metadata or any pagination, but for a two-required-param list tool this is close to 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 description coverage is 100%, and both parameters (company UUID, environment enum) are fully documented in the schema, so the baseline is 3. The description adds no parameter-level meaning beyond what the schema already provides.

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

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

Specific verb plus resource ('List provider integrations') with a clear statement of what the payload contains: required fields and saved metadata. It is distinguishable from the write sibling summer_integrations_save by the 'list' verb, but the description never names or contrasts that sibling explicitly, so it falls 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 implied by the verb 'List' and the required company/environment scope, but there is no explicit when-to-use guidance, no prerequisites, and no mention of the alternative (summer_integrations_save) that an agent might otherwise pick. Adequate but with a clear routing 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 cover the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false), so the bar is lower. The description still adds real value beyond them: it clarifies no secrets are stored here and that the definition alone grants no runtime access, describing the follow-up CLI workflow. It does not explain the destructive/overwrite semantics implied by destructiveHint=true, which is the main remaining gap.

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

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

Three short sentences, front-loaded with the core purpose before the workflow caveat. Minimal waste, though the CLI/verification tail could be tightened slightly. Structure is good and every sentence carries 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 save tool with no output schema and annotations already declaring the safety profile, the description supplies the key missing context: no secret values, and no runtime access from the definition. The overwrite/destructive behavior flagged by annotations is not addressed, but overall an agent has what it 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 57%, above the midpoint baseline. The schema already documents company, environment, idempotency_key, expected_version, and fields.name. The description only adds the general notion that fields hold names/labels (no values), which marginally clarifies the fields array but does not compensate for the undocumented required params (name, integration).

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: 'Define a custom integration's credential names and labels,' reinforced by 'No secret values.' This distinguishes it from the credentials-writing siblings, though it never names them explicitly. Clear enough to pick apart from summer_credentials_set, but the differentiation is implied 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?

Gives useful workflow context ('Saving a definition does not establish runtime access; upload secrets through the local CLI and verify an agent-usable path'), which tells the agent this is one step in a sequence. However, it never points to a specific alternative tool for the secret-upload step and provides no exclusions or prerequisites for when to call this versus other save tools. Usage is implied rather than explicit.

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=true, so the safety profile is fully covered structurally. The description adds nothing behavioral beyond this — no pagination, no result-shape hints, no note on approval-state semantics even though it explicitly names 'approval state' as a return category. It essentially duplicates the readOnly annotation in prose.

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, so it is not padded. But it is a pure title restatement, so the one sentence does not really earn extra place — it adds no information the title had not already delivered.

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 should ideally explain the return shape; it does list the four content categories (runs, plans, approval state, receipts), which partially compensates. Missing are pagination/volume expectations, any filtering behavior, and the fact that it is a multi-entity aggregate read, which matters for an open-world, case-scoped 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?

With 3 required parameters at ~67% schema description coverage, the schema documents company ("Summer company ID") and environment (enum), and the description adds only the scoping concept 'for a case', which maps to the third parameter. It does not explain ID formats or how the three identifiers interact, but the baseline is met since the schema carries most of the burden.

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 verb (Read) and enumerates concrete resources (investigation runs, saved plans, approval state, execution receipts) scoped to a case, so the agent knows what data it retrieves. However, it is a verbatim restatement of the title and offers no differentiation from the sibling summer_investigations_request, which is the write-path counterpart. The purpose is inferable but the line between reading and requesting investigations is left to the agent to guess.

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 statement of prerequisites, and no mention of alternatives such as summer_investigations_request for kicking off a new investigation. The agent must derive the usage boundary purely 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?

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The added sentence 'Completion is not approval' is genuinely non-obvious workflow semantics that goes beyond the annotations, but it is cryptic and omits what gets destroyed, whether the call is asynchronous, and what 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?

Two short, front-loaded sentences with no filler; the dual purpose is stated first. It would score higher if it used its available space to resolve the ambiguity of the second sentence rather than leaving it as a fragment.

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 destructive, non-idempotent, open-world tool with five parameters, 60% schema coverage and no output schema, the description says nothing about the response, async behavior, retry semantics (beyond the schema's idempotency_key hint), or what happens after a request is 'completed'. It is materially under-specified for this complexity.

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

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

Schema coverage is 60%; the case/company/environment/idempotency_key descriptions carry some of the load, and the description does signal that the 'request' parameter has two shapes (investigate vs revise-with-feedback). That mapping adds modest meaning, but the description still leaves the actual mode fields to 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 (ask/investigate) plus resource (the case) and names a second mode (revise a saved plan). It is clearly distinguishable from siblings like summer_investigations_list, though it never distinguishes itself from adjacent action tools such as summer_verification_run or summer_actions_prepare.

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 two modes ('investigate' vs 'revise a saved plan') are enumerated, which mirrors the schema's oneOf rather than giving real guidance. There is no statement of when to pick this tool over summer_verification_run, summer_actions_prepare, or summer_investigations_list, and no prerequisites 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds real context about blast radius ('used by all roles and environments'), but omits retry/idempotency guidance despite an idempotency_key parameter existing.

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 with no filler, and the action is front-loaded before the constraint. The 'original revision history' clause is slightly opaque but takes minimal space.

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 7-parameter, 5-required destructive write with no output schema, the description says nothing about what the required fields mean, why a reason is mandatory, or what the upload returns. The usage constraint is covered but the invocation surface is 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 only 43% and the description mentions no parameter by name or meaning. The required 'reason' field, the 'path' pattern, tags, and idempotency_key semantics are left entirely to the schema, so the description 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?

States a specific verb and resource ('Upload a new company knowledge document') and the 'new' qualifier distinguishes it from the sibling summer_knowledge_edit. The trailing phrase 'with original revision history' is somewhat ambiguous but the core purpose is unmistakable.

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 states a when-not condition: 'An existing document must be read and edited instead.' It routes the agent away from this tool for existing docs, though it never names the sibling (summer_knowledge_edit) explicitly and gives no positive preconditions.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description usefully adds blast-radius context ('Affects every environment and later runs'), but it does not explain what happens on a revision mismatch (conflict error vs. overwrite) or confirm the irreversibility of the edit.

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

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

Two short sentences with the primary action and the concurrency requirement front-loaded, and a secondary impact statement after. No filler, though it is arguably sparse relative to the tool's destructive nature.

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 destructive, non-idempotent mutation with 7 parameters and no output schema, the description covers the core action, the concurrency guard, and the blast radius. It omits permission requirements, conflict/error behavior, and what the agent should do on a stale revision, which leaves meaningful 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 only 43%, and the description adds real semantics for two parameters: 'expected revision' frames revision as an optimistic-concurrency token, and 'a reason' implies a required audit justification. However, company, document, content, status, and idempotency_key receive no added meaning, so it only partially compensates 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 specific verb and resource ('Edit an existing company knowledge document') and can be distinguished from siblings like summer_knowledge_create, summer_knowledge_get, and summer_knowledge_history without opening the schema. It does not explicitly reference those siblings, 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?

There is no when-to-use guidance, no mention of prerequisites or alternatives (e.g., summer_knowledge_create for new docs, summer_knowledge_history for revisions). The mention of 'expected revision' faintly implies a read-before-write workflow, but the agent must infer 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds nothing beyond them: no auth/permission requirements, no behavior when the document ID is unknown, no note that it resolves the latest revision rather than a specific one. It does not contradict the annotations.

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

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

A single short sentence, front-loaded and free of filler. It is efficient, but because it merely mirrors the title it earns less than a maximally useful one-liner would.

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 with full annotation coverage and a complete schema, this is roughly sufficient. However, with no output schema, the description only vaguely gestures at the return ('document and its current revision') without indicating what that payload contains, leaving a minor 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% with two fully documented parameters (company UUID, document ID pattern), so the schema carries the semantics. The description's mention of 'company knowledge document' loosely maps to the two params but adds no format or constraint detail. 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 (Read) and resource (one company knowledge document plus its current revision). The phrases 'one' and 'current revision' implicitly separate it from knowledge_list (many documents) and knowledge_history (all revisions), though no sibling is named. It is a verbatim duplicate of the title, so it adds no clarifying detail of its own.

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

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

There is no explicit when-to-use, when-not-to-use, or named alternative. The only hint is 'current revision,' which weakly implies using knowledge_history for older revisions, but nothing is stated. An agent must infer selection from the sibling names alone.

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, openWorldHint and destructiveHint=false, and the description adds nothing beyond them. It does not disclose ordering of revisions, whether the history is paginated, or what the response contains, which is exactly the extra context this one-line description could have supplied.

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 or repetition. It is efficient, though the brevity edges toward under-specification rather than optimal conciseness.

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 annotation-independent detail, the description leaves the return shape (list of revisions? authors? timestamps?), ordering, and pagination behavior entirely unexplained. For a history endpoint with an offset parameter, 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 coverage is 67%: company and document carry descriptions, but the offset parameter is undocumented in both schema and description. Since history retrieval is pageable, the description should have explained the offset/pagination semantics rather than leaving it opaque.

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

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

The description names a specific verb (read) and resource (edit history of a company knowledge document), which clearly separates it from summer_knowledge_get and summer_knowledge_edit. It does not, however, explicitly contrast itself with those siblings, so an agent must infer the distinction from the name alone.

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 (e.g. needing a valid document ID before calling), and no pointer to alternatives such as summer_knowledge_get for current content versus history. Usage must be inferred entirely from the tool 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds the company-wide (not per-environment) scoping fact, which is genuine context, but says nothing about pagination behavior or result volume despite an offset parameter.

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

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

Two short sentences with the core action front-loaded and zero filler; the second sentence carries the one non-obvious fact.

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 should ideally explain what a 'document' record looks like or how listing/pagination works. It covers the resource and its scope but leaves return shape, filtering semantics of 'query', and pagination unaddressed.

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%: just 'company' is documented ('Summer company ID'), while 'query' and 'offset' carry no descriptions. The description adds no meaning for any of the three parameters, so it fails to compensate for the 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?

Specific verb (List) plus resource (company knowledge documents) and a scope qualifier ('current'), which separates it adequately from summer_knowledge_get and summer_knowledge_history. It does not explicitly name sibling tools, 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?

'current' combined with the sibling summer_knowledge_history implies this is the live/snapshot listing rather than the audit trail, but that contrast is left for the agent to infer. 'Knowledge is company-wide, not per environment' is a useful scoping rule, yet there is no explicit when-to-use or when-not-to-use statement.

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=true, so safety is fully covered by structured data. The description adds nothing beyond the title — no mention of permission scoping, what settings are returned, or how the managed-runtime flag is determined.

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 waste, but it is a verbatim echo of the title and therefore contributes no new information to the agent. Brevity here reflects duplication rather than efficiency.

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

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

With no output schema, the description should explain what 'assistant settings' include and what the managed-runtime flag means, but it does not. For a settings-read tool with a two-param scope, the definition leaves the return payload entirely opaque.

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 both parameters are well described (company UUID, environment enum), so the schema carries the load. The description's 'per installation' scope actually misleads, since neither parameter is an installation identifier — potentially confusing an agent about what keys the read.

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?

Contains a specific verb ('Read') and resource ('assistant settings', 'managed runtime enabled'), which is better than a bare name restatement. However, it offers no differentiation from close siblings like summer_messenger_assistant_update or summer_messenger_installations_list, and the phrase 'per installation' doesn't map cleanly onto the actual company/environment parameters.

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 indication of when to use this versus summer_messenger_assistant_update or the installations tools, and no prerequisites or exclusions stated. The agent must infer usage purely from the tool 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?

Annotations already flag destructiveHint=true and non-idempotent behavior; the description usefully adds the constraint that the spending limit cannot be raised through this call. However, it does not warn that settings is a full replacement of instructions/knowledge, which is the main destructive risk an agent needs to know about.

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 the key constraint. No filler, though the second sentence could be joined more clearly to budget_cents.

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 destructive, non-idempotent mutation on a nested settings object with four required sub-fields, the description leaves out replacement semantics, permission requirements, and stale-revision failure behavior. With no output schema and only 50% schema coverage, more disclosure was needed.

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% and description supplies meaning for two undocumented parameters: 'expected revision' (optimistic concurrency) and the budget ceiling rule. It says nothing about company, environment, installation, or idempotency_key, so it only partially compensates 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?

A specific verb ('update') plus resource ('assistant instructions and knowledge') that clearly distinguishes it from the read-only sibling summer_messenger_assistant_read. It omits the enabling toggle and budget field, but the core purpose is unmistakable.

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 'with the expected revision' hints at optimistic concurrency but never tells the agent to fetch the current revision first, nor what happens on a stale revision. There is no explicit when-to-use, no prerequisite chain (read → update), and no exclusion versus summer_messenger_installations_update.

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 destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is largely covered. The description adds one genuine behavioral fact — that pausing halts automatic replies immediately — but omits what happens to in-flight or queued replies, permission requirements, and the effect on the human side. Note the schema's idempotency_key sits in mild tension with idempotentHint=false, though the description does not itself contradict annotations.

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

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

Two sentences with no filler; the operative action and its scope come first, and the single behavioral caveat ('stops automatic replies immediately') is placed second. 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 5-parameter mutation with no output schema, the description covers the core action and its immediate effect but not permissions, return behavior, or what 'take over' means operationally for message routing. Rich annotations carry most of the remaining burden.

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 60%, with company and environment documented but conversation and paused left bare. The description implicitly explains the dual role of the 'paused' flag ('pause ... or ask it to resume'), which is real added meaning, but it says nothing about the company/environment/conversation identifiers or the idempotency key 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 names a concrete action (pause/resume) and a precise resource scope ('in one conversation'), which separates it from the account-level assistant configuration siblings like summer_messenger_assistant_update. It does not explicitly name those siblings, so an agent still has to infer the scope distinction.

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

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

Usage is implied by 'so a person can take over, or ask it to resume' — this conveys the human-handoff scenario — but there is no explicit when-to-use versus the assistant-level tools, no prerequisites, and no stated exclusions. Adequate but inferential.

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 it is a destructive, non-read-only, non-idempotent write. The description goes beyond them by disclosing that the one-time signing key is delivered to a trusted local helper and never appears in model-visible output, plus that a local CLI command may be returned. That is meaningful operational context an agent cannot get from the annotations.

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

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

Three short sentences, front-loaded with the core action and its distinguishing detail, followed by the two behavioral facts that matter. Little wasted text, though the secret-handling sentences 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?

With no output schema, the description usefully notes that a local CLI command may be returned and that secrets are not exposed, covering the key return-behavior question. Given the rich nested input schema, this is largely complete, though permission prerequisites (e.g. messaging.activate) are only visible in the schema.

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 80%, so the schema already documents most parameters well (including the id-idempotency rationale and environment enum). The description only echoes the client-chosen ID concept and adds nothing about nested settings, origins, or routing.

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 (Create) and resource (installation) and adds the distinguishing detail that the ID is client-chosen, which separates it from generic create tools. It does not explicitly name its siblings (update, list, rotate_key), so full sibling differentiation 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 explicit guidance on when to use this versus installations_update, rotate_key, or list. The retry/duplicate-avoidance rationale is only inferred from the phrase 'client-chosen ID' and the schema, not stated as usage 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds one genuine disclosure beyond that — signing keys are never returned — which is useful redaction context, but nothing about result shape, pagination, or auth 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 short sentences with zero waste; the primary action is front-loaded and the redaction caveat follows. 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-only list with rich annotations and no output schema, the description covers what the tool returns and what it deliberately omits. Minor gaps remain around result fields and pagination, but nothing critical 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 (company UUID, environment enum) are documented in the schema, so the baseline is 3. The description adds no additional parameter meaning, such as how the environment scopes results.

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 Messenger installations") plus a scope qualifier ("in this environment"). The verb cleanly separates it from the sibling mutation tools (installations_create, installations_update, installations_rotate_key), though it never names an alternative 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 guidance on when to call this versus related tools, and no prerequisites or exclusions are stated. The intended use is only implied by the name and verb.

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?

Adds real context beyond the annotations: it discloses the side effect ("Existing signed sessions end"), the security boundary ("key goes to the trusted local helper only"), and a return behavior ("Returns a local CLI command when a secret is involved") despite no output schema. This is consistent with destructiveHint=true and adds value without contradicting any hint.

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, front-loaded with the action, and every sentence carries a distinct piece of information (purpose, consequence, key destination, return behavior). 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?

Annotations cover the destructive/open-world profile, and the description covers the main side effect and partial return behavior. However, for a 5-param mutation it omits auth/permission requirements and the meaning of expected_version and idempotency_key, leaving notable 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 60%, and the description mentions none of the five parameters (company, environment, installation, expected_version, idempotency_key). With schema doing part of the work but a 40% gap, the description fails to compensate by explaining the optimistic-concurrency expected_version or idempotency 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+resource ("Issue a new signing key") that is clearly distinct from sibling installations_create/update/list actions. It doesn't name a sibling to differentiate from, but the rotation action 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?

No explicit when-to-use or when-not guidance, and no alternative named from the large sibling set. Usage is only implied by the destructive consequence "Existing signed sessions end," which lets an agent infer this is a deliberate rotation rather than a routine edit.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds one genuinely new behavioral fact (the signing key is preserved) but never explains what the destructive update actually replaces, what a version conflict does, or what permissions are needed.

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 that are front-loaded with the action. Both sentence fragments earn their place, though the second is terse enough that it reads more like a bullet than a complete statement.

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 destructive, non-idempotent mutation with 6 parameters, a nested settings object, 50% schema coverage, and no output schema, the description is too thin. It omits what gets overwritten, version-conflict behavior, and the production permission requirement hinted at in the schema.

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%, and the description adds real meaning to one parameter by framing expected_version as an optimistic-concurrency guard (the schema only shows it as an integer). However, it says nothing about company, environment, installation, or idempotency_key, leaving half the surface undocumented.

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 (update installation settings) and even differentiates itself from the sibling rotate_key operation by noting it 'Keeps the signing key.' The 'expected version' phrase hints at optimistic concurrency. It is clear but does not fully name its sibling set.

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

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

There is no explicit when-to-use statement, but 'Keeps the signing key' implicitly excludes the rotate_key path, giving some usage signal. No prerequisites (e.g., required capability/messaging.activate for production) or alternatives are named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond that — no note on result completeness, ordering, scoping, or rate limits — so it contributes no behavioral context of its own.

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 short sentence is front-loaded and free of waste, but it is under-specified rather than genuinely concise — it consumes the entire description budget restating the title without adding usable content.

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 should compensate by explaining what the list returns (fields, pagination, empty results), and it does not. For a read tool sitting alongside a save sibling, the absence of any scoping or return-shape information leaves the definition incomplete.

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 required parameter 'company' is documented in the schema as 'Summer company ID'. With full schema coverage and only one parameter, baseline 3 is appropriate; the description adds no format or 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?

The description is a verbatim restatement of the tool title ('List the company's service accounts') and adds no differentiating information. While it does name a verb and resource, it is a tautology with the title and gives no basis for distinguishing it from siblings like summer_service_accounts_save or summer_credentials_list.

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

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

There is no when-to-use guidance, no mention of alternatives (e.g., the companion save tool), and no stated prerequisites such as permissions or pagination expectations. The agent is left to infer that this is the read counterpart of summer_service_accounts_save.

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 destructiveHint=true, openWorldHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the secret is never returned inline but routed to a trusted local helper, and a local CLI command is returned when a secret is involved. It does not, however, mention permission requirements or the optimistic-concurrency behavior implied by the required expected_version.

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 with the purpose front-loaded and the two behavioral facts following immediately; there is no filler. The phrasing 'A new secret goes to the trusted local helper only' is slightly indirect but still 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?

This is a destructive, open-world mutation with 9 parameters, 6 required, a required expected_version concurrency token, and no output schema — yet the description explains almost none of that. An agent cannot infer from the prose how to set disable/rotate_secret or what version to pass for a brand-new account, which is a significant gap for a destructive 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 low (33%), so the description is expected to compensate and does not: name, scopes, account, disable, rotate_secret and expected_version are given no meaning in the prose. The four mode-switching flags in particular are undocumented anywhere, leaving the agent to guess how create vs update vs rotate vs disable is actually selected.

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 (service account) and enumerates the four operations it performs (create, update, rotate, disable), which maps cleanly onto the save/upsert semantics of the tool. It clearly separates itself from the read-side sibling summer_service_accounts_list, though it never explicitly names that sibling or other alternatives.

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 choose each mode — nothing tells the agent that disable=true means deactivation or rotate_secret=true means key rotation, nor when to prefer this tool over siblings like summer_messenger_installations_rotate_key. The only contextual hint is the note about secret delivery, which is behavioral rather than usage-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?

The annotations declare destructiveHint=true and readOnlyHint=false, yet the description brands the operation 'harmless', which misleads the agent about side effects and reversibility. The one genuinely useful note ('unsupported checks are reported as unsupported, never as passed') concerns result semantics, not the destructive behavior the annotations flag.

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 no filler. It is efficient, though the brevity contributes to the gaps in the other dimensions rather than being purely virtuous.

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 destructive, open-world, non-idempotent mutation tool with no output schema and only 75% parameter documentation, the description is far too thin. It omits what happens on failure, how targets relate to the checks, and why a verification operation carries a destructive hint.

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 75%, so the schema already documents company, environment, and idempotency_key; baseline 3 applies. The description adds no parameter detail at all, leaving the targets enum (credentials/providers/slack/messenger) with no explanation of what each target verifies.

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 restates the title ('Run supported harmless checks') without saying what resource is being verified or what 'checks' actually inspect. With siblings like summer_capability_checks_test and summer_capability_checks_report in the list, an agent cannot tell what makes this tool distinct. The verb is present but the resource and scope are left undefined.

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 the capability-check siblings, and no prerequisites, environment caveats, or exclusions are given. The only guidance is an implicit 'run checks', which the agent must infer 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered without the description. The phrase 'delivery state' adds a small amount of context about what is surfaced in the result, but nothing about pagination, filtering, or result volume.

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 or repetition. It is efficient, though arguably terse to the point of under-specification rather than being a model of well-structured guidance.

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 list tool with a fully documented two-parameter schema and no output schema, the description is minimally adequate. It does not address pagination, result limits, or how delivery state is represented, leaving gaps an agent may need to discover at call time.

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

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

Schema description coverage is 100% – both 'company' (Summer company ID) and 'environment' (staging/production enum) are fully documented in the schema. The description adds no additional meaning, 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 specific verb ('List') and resource ('webhook endpoints and delivery state'), so the agent knows exactly what it returns. It does not differentiate itself from siblings summer_webhooks_save or summer_webhooks_replay, but the verb alone makes the distinction obvious.

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 summer_webhooks_replay or summer_webhooks_save, nor any mention of prerequisites such as needing a company/environment scope. Usage must be inferred entirely from the name and verb.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so safety framing is partly covered. The description adds one genuinely useful trait ('Receivers deduplicate by event ID'), but omits what gets re-delivered/overwritten, permission needs, and rate limits. With annotations carrying the safety profile, this is an average add.

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 and free of padding. The first sentence, however, restates the title almost verbatim, which is mildly redundant rather than additive.

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 6-parameter, destructive, non-idempotent mutation tool with 50% schema coverage and no output schema, two sentences is thin. It never states what the call returns, what the cursor references, or how much is re-queued by default, leaving the agent under-informed for a side-effecting operation.

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% (after, limit, and webhook are undocumented in the schema). The description adds meaning to 'after' (cursor semantics) and implies the endpoint maps to the webhook parameter, but gives no explanation of limit or the event-ID format expected in 'after', so it only partially compensates.

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 ('Queue ... for delivery again') and resource ('past events after a cursor') with a scoping detail ('to one endpoint'). It is clearly distinguishable from list/save siblings, but it never names or contrasts those siblings, which is what a 5 would require.

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

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

There is no explicit guidance on when to use this tool versus alternatives, no preconditions, and no warning about when replaying is inappropriate. The dedup note is behavioral context, not usage guidance, so this sits at 'no 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 destructive=true, openWorld=true, idempotent=false, so the safety profile is covered. The description adds genuinely new behavior: the new signing secret is delivered to a trusted local helper rather than returned, and a local CLI command is returned when a secret is involved — crucial for an agent that might otherwise expect the secret in the payload.

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, with the operation set front-loaded and the secret-handling caveat immediately after. Every sentence carries 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 9-parameter destructive mutation with no output schema and sub-50% schema coverage, the description covers the secret/CLI return behavior well but omits the semantics of half the parameters and any guidance on optimistic-concurrency failure. Annotations carry the safety burden, which keeps this at a minimum-viable level rather than lower.

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 44% across 9 parameters, so the description must compensate and does not. It never explains disable, event_types, expected_version semantics (optimistic concurrency, 0 for new resources), or idempotency_key, even though the idempotentHint=false annotation makes the latter non-obvious.

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

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

Names the specific resource (signed webhook endpoint) and enumerates the four operations it performs — create, update, rotate, disable — which cleanly separates it from summer_webhooks_list and summer_webhooks_replay. It does not explicitly name those siblings, but the resource/operation combination is unambiguous.

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

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

The description lists the operations but never says when to choose this tool versus webhooks_replay or webhooks_list, nor what preconditions apply (e.g. expected_version=0 for creation). The mode selection is left entirely implicit in the disable/rotate_secret flags.

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