omnara

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

The description is exceptionally rich about destroy-vs-retain semantics (what is torn down, what survives, no-op on already-archived), which goes well beyond the annotations. However, it contradicts the annotations on idempotency: it states that archiving an already-archived agent 'is a no-op that returns the agent unchanged', which is exactly the idempotent behavior that idempotentHint=false denies. The rest (destructiveHint=true, readOnlyHint=false, openWorldHint=false) is consistent, so this is a partial rather than total contradiction, but it is a real inconsistency an agent could act on.

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

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

The definition is front-loaded with the verb and the full effect list, followed by retention guarantees and then the idempotent no-op case, in a deliberate order. Despite its length, every clause carries distinct operational information (nothing is restated from the name, title, or schema), so no sentence 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 destructive, three-id mutation tool with no output schema, the description covers effects, retention, listing visibility, and repeat-call behavior – enough to call it safely. Remaining gaps are modest: no indication of required authorization/grants, or what happens if runtime cancellation is asynchronous or fails partway through the teardown sequence.

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?

All three parameters (orgID, agentID, projectID) are documented in the schema with patterns and descriptions, so schema coverage is 100% and the baseline is 3. The description adds nothing parameter-specific – it never mentions ids, scoping, or which org/project must own the agent – so it neither compensates nor is required to.

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+resource (archive the agent) and then enumerates the exact scope of that verb: runtime cancellation, queued inputs, processes, pending wakeups, machine bindings, pooled machines, cron triggers. It implicitly separates itself from siblings like agents_cancel by making clear that this is a lifecycle retirement operation, not a runtime-only cancellation, and the retention semantics ('event history stay readable by id', 'leave listings') further pin down what 'archive' means here.

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 rather than stated: an agent would read this as 'use me to retire an agent while keeping its history', and the no-op note gives a re-invocation condition. However, there is no explicit when-to-use/when-not-to-use guidance against the nearest alternative, agents_cancel, nor any statement of prerequisites or permissions.

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?

Goes well beyond the destructiveHint=true annotation by specifying exactly what is destroyed (unfinished tool calls, open interactions, pending steering, in-flight processes) and, critically, what survives (agent stays active, queued messages retained, already-returned processes keep running). It also discloses the no-op return contract ('affected false'), which the annotations cannot convey.

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

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

Three tightly packed sentences, front-loaded with the core action, then the survival semantics, then the edge case. Every clause carries information an agent needs to decide whether and how to call the tool; nothing is redundant.

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

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

For a destructive turn-cancellation tool with no output schema, the description covers the mutation scope, the post-condition state of the agent, and the no-op response ('affected false'). Combined with annotations and a fully documented schema, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and the four parameters (agentID, orgID, projectID, actor) are fully documented in the schema, so the baseline of 3 applies. The description adds no parameter-level syntax or format detail beyond what the schema already states.

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

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

States a specific verb and resource ('Stops the agent's current turn') and immediately enumerates the exact scope: unfinished tool calls, open interactions, in-flight run_command processes, and pending steering messages. This is distinguishable at a glance from siblings like agents_archive or agents_input, which act on the agent's lifecycle or feed it input rather than halting an in-progress turn.

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 clear triggering context (a turn must be in progress) and the null condition ('Returns affected false and changes nothing when no turn is in progress'). It does not explicitly contrast itself with alternatives such as agents_archive or agents_input, so the routing guidance is implicit rather than spelled out.

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/non-destructive, so the safety profile is covered. The description goes beyond them with real behavioral detail: exclusive boundaries, which cursor field each direction yields, and the explicit precedence rule that before_sequence overrides after_sequence. It stops short of stating the page-size ceiling or end-of-log behavior.

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

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

Three dense segments with the core behavior front-loaded and no filler; every clause carries information. The semicolon-chained construction is slightly run-on, which keeps it from 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?

There is no output schema, so the description must carry return-value context. It helpfully names next_after_sequence and next_before_sequence, but never explains what those cursors contain, when they are absent at the log's end, or how the returned event objects are shaped — a notable gap for a paginated list tool.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above baseline by adding the precedence rule between after_sequence and before_sequence, which the schema does not state, plus the direction each boundary implies. It adds no detail for limit, orgID, agentID, or projectID 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 opens with a specific verb+resource ('Returns one page of agent events') and adds the ordering guarantee ('chronological within the page'), which an agent can act on immediately. It does not distinguish itself from lookalike siblings such as agents_interactions_list or agents_get, 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?

It clearly explains how to drive forward vs backward pagination and which parameter wins on conflict, which is genuine invocation guidance. But it never says when to choose this tool over a sibling (e.g. interactions vs events), so usage against alternatives 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=false, so the safety profile is covered. The description adds genuine value beyond that by scoping what is and is not returned ('The conversation isn't included'), preventing an agent from assuming it can read transcripts after this call. No auth or rate-limit context is added, keeping it short of a 5.

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

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

Two sentences, zero filler. The positive return list is front-loaded and the exclusion clause is placed last where it reads as a caveat rather than a delay.

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 bears the burden of describing return values – and it does so explicitly by enumerating state, model, profile, config ID, activity enum values, machines, and MCP connection states, plus the negative 'conversation isn't included'. For a simple, fully-documented-parameter read tool, nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100% – all three identifiers are documented with their org_/agt_/proj_ prefixes and regex patterns – so the schema carries parameter semantics. The description adds nothing about parameter meaning or interaction, which is the correct baseline of 3 when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Returns one agent's state, model, profile...') and enumerates the exact fields returned, which is far more informative than a generic 'get'. The word 'one' implicitly separates it from agents_list, so an agent can distinguish the two without opening schemas.

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 shape of the tool (fetch a single agent), but there is no explicit when-to-use guidance, no prerequisite note (e.g., that agentID/orgID/projectID must come from agents_list or a launch call), and no mention of siblings like agents_events_list as alternatives for activity history.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine timing behavior (queued waits until the agent is ready; steering lands at the next model call), but says nothing about permissions, side effects on the agent's current turn, or limits.

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

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

Two sentences, purpose front-loaded, and the second sentence spends its words on the one non-obvious decision (delivery mode). No filler or restatement of the name.

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

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

With seven parameters, nested objects, media blocks and no output schema, the description covers purpose and delivery semantics but is thin on interaction with the sibling interaction tools and on what "stored input" is retrievable as. The rich schema carries most of the remaining burden, so 3 is the minimum-viable level.

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%, so the baseline is 3. The description goes beyond the bare delivery_mode enum by defining what "queued" and "steering" actually mean and which is the default, adding meaning the schema alone does not convey.

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 ("Sends a message to an agent") plus the effect ("returns the stored input"), so the agent knows exactly what the call does. It does not explicitly differentiate itself from adjacent siblings such as agents_interactions_resolve or agents_cancel, 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?

The description explains the two delivery modes and establishes queued as the default, which is real usage context. However it never states when to prefer this tool over siblings, nor when steering is the right choice versus queued beyond a bare timing distinction.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: results are ordered 'oldest first', each entry carries its form and answers, and state filters by open/resolved/canceled. No return format for pagination is given, but it meaningfully enriches the read semantics.

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

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

Two compact sentences, front-loaded with the verb and resource, then the ordering/content and the state filter. No filler; every phrase 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?

With no output schema, the description usefully states what is returned (each interaction's form and answers) and the ordering. For a 7-parameter read tool with high schema coverage and clear annotations, this is nearly complete, though it could mention pagination behavior expected of cursor/limit.

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%, so most parameters (limit, cursor, IDs) are already documented in the schema. The description reinforces the state filter by naming its three enum values, but adds little beyond what the enum already supplies. Baseline 3 for high schema coverage is appropriate.

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

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

States a specific verb and resource ('Lists an agent's permission prompts and ask_question questions') and even describes the returned content (form and answers). It's clear what the tool does, but it doesn't differentiate itself from the sibling agents_interactions_resolve, which an agent might confuse it with.

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

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

The description implies the use case (listing an agent's pending prompts/questions) and explains the state filter values, which hints at when to use it. However, it gives no explicit when-not guidance and never points to the sibling agents_interactions_resolve for handling those interactions.

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

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

Annotations already declare this as a non-readonly, non-idempotent, open-world mutation, so safety is covered. The description adds real context beyond that: the side effect (the paused agent resumes) and the return ('returns the resolved interaction'). It does not address retry/idempotency behavior for a tool flagged idempotentHint=false, which keeps it below 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?

Two tight sentences, front-loaded with the action and its effect, followed by the answer-format rules that an agent needs before calling. No filler or repetition of structured fields.

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-required-param mutation with nested objects and no output schema, the description covers purpose, side effect, and the awkward answer-index convention well. It stops short of explaining failure modes (e.g. answering an already-resolved interaction) or what the returned interaction contains, which would round it out.

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 83%, so the baseline is 3, but the description genuinely adds semantics the schema lacks: option_indices are zero-based, exactly one answer is sent per question, and permission prompts map 0=Allow / 1=Deny. The schema only constrains indices as non-negative integers, so this mapping is new information.

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

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

The description gives a specific verb and resource: it 'answers an open permission prompt or question so the paused agent resumes.' That is far more precise than a restated title and tells the agent exactly what effect the call has. It never names a sibling (e.g. agents_interactions_list or agents_input), so it falls short of the 5 criterion requiring explicit 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 context is clear: this is the call that un-pauses an agent stuck on an open prompt or question. However, it states no exclusions or alternatives (e.g. when to use agents_input instead of resolving an existing interaction), so the agent must infer the boundary from the description 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=false, destructive=false, openWorld=true, idempotent=false, but the description adds substantive behavior the agent cannot get elsewhere: the whole operation is one atomic transaction, permissions differ per capability, and idempotency-key replay returns the existing agent without applying the new retry body or re-resolving integration references. That is exactly the extra context annotations cannot carry.

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 dense but front-loaded sentences: core action first, then permission conditions, then replay semantics. Every sentence carries information, though the middle sentence packs two distinct permission rules that could be split for faster scanning.

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 an 11-parameter, nested-object, no-output-schema mutation tool, the description covers atomicity, permissions, and replay well, but omits the profile-launch path present in the schema and never says what a successful launch returns (the new agent). Those gaps are modest given the rich schema descriptions.

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 91%, so the schema already documents nearly every parameter in detail, and the description's parameter mentions (tools, subscriptions, interaction handlers, initial input) largely restate the schema. It adds only marginal framing, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('launch') and enumerates exactly what the launch transaction can carry: agent-local integration tools, subscriptions, interaction handlers, and an attributed initial text input. An agent can distinguish this from siblings like agents_get, agents_update, agents_input, or configs_create without opening the schema.

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

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

Gives permission context for two modes ('adding integration capabilities requires project management permission; launching an existing config requires agent operate permission'), which implies when each mode applies, but never states when to use config vs config_source vs profile, nor names an alternative tool. 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 readOnly, idempotent, and non-destructive, covering the safety profile. The description adds useful default-exclusion behavior for archived agents and subagents, but doesn't mention pagination behavior or the inclusion of usage data despite that being a 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 sentences with zero waste, front-loading the primary action and default behavior. 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 list tool with rich schema coverage and read-only annotations, the description is nearly complete. It covers scope and defaults, but could mention that results are paginated with cursors, a key aspect for an agent consuming the output.

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

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

Schema description coverage is 100%, so all parameters are already well-documented in the schema. The description adds only minor context about default sorting and exclusion, not enriching parameter meaning beyond what the schema 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?

States a specific verb and resource ('Lists the project's agents') and adds scope detail about activity and ordering. It is clearly distinguishable from siblings like agents_get (single agent) and agents_archive (mutation).

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 clear default behavior and a condition for expanding results (archived/subagents excluded unless requested), which implicitly guides filtering. However, it doesn't name alternatives like agents_get for fetching a single agent, so explicit routing to siblings is missing.

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 destructiveHint=true annotation, it discloses exactly what is destroyed (processes stopped on removed machines, machines deleted from removed pools), the timing of changes (model/instruction/tool at next model call vs machine changes immediately), and the return value. This is rich behavioral context the annotations cannot convey.

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

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

Three sentences, front-loaded with the core action and scope, followed by timing/destruction details and the invocation rule. Every sentence carries distinct information with no filler.

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

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

Despite no output schema, the description states what is returned (the new agent_config), covers destructive side effects and change timing, and specifies the full-config requirement. Nothing essential for a correct call 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 coverage is 100%, so the baseline is 3, but the description adds real meaning about the 'source' parameter: it must be a complete config rather than a partial patch, clarifying replacement semantics. That elevates it above the schema-only 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 uses a specific verb and resource ('Replaces an active agent's config') and distinguishes itself from siblings like agents_launch and configs_create by scoping to an already-active agent. An agent can tell this is a config mutation on a live agent without opening any schema.

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

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

It gives a clear invocation rule ('Send the complete config, not a patch') and context that the target is an active agent whose conversation is not restarted, which helps separate it from launch/create flows. It stops short of naming an explicit alternative or a when-not condition, so it is strong but not fully 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?

With annotations only declaring the safety profile (writes, non-destructive, closed-world), the description adds real context: configs are immutable, the call returns the compiled config, and resubmitting the same source deduplicates to the existing config as long as name references still resolve. That dedup caveat sits in mild tension with idempotentHint=false, but the qualification ('as long as its names still resolve') keeps it from being a hard contradiction. Auth requirements, error behavior on unresolved names, and rate limits are unstated.

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, both front-loaded with the operative verb and resource, no filler, and the surprising resubmission semantics placed after the core action. Every clause earns its place.

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

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

No output schema exists, but the description states the compiled config is returned, so the agent knows what comes back. For a four-required-parameter creation tool whose schema is fully self-documented, the only meaningful omissions are failure modes (e.g., unresolved resource names) and permission requirements.

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 all four required parameters (orgID, projectID, source, source_format) carry their own descriptions, so the baseline is 3. The description clarifies that source is YAML or JSON and implies the returned/created entity is the config itself, but adds no new syntax or constraint detail beyond the schema.

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

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

States a precise verb and resource ('Compiles and saves an immutable agent config') plus the accepted input forms (YAML or JSON) and names representative config fields (instruction, model, tools, machine_sources). It is trivially distinguishable from the only related sibling, configs_get, without opening either schema.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no routing to alternatives such as configs_get for reading an existing config. The resubmission sentence is a behavioral guarantee rather than a usage rule, so the agent must infer when to reach for this tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: it explains that derived configs (subagents, integration launches) have no source, pre-empting a null field the caller would otherwise be surprised by.

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

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

Two tight sentences, no waste, with the primary behavior front-loaded and the derived-config edge case following. 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?

With no output schema, the description carries the return-value burden and does so reasonably, covering the compiled definition and the source field. It is complete for a simple idempotent getter, though it never states whether a missing config errors or returns empty.

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

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

Schema description coverage is 100%, so all three IDs are already documented with patterns in the schema. The description adds no parameter-level detail, warranting the baseline 3.

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

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

States a specific verb and resource (Returns one agent config) and clarifies the payload shape (compiled definition with names resolved to IDs, plus source). It is instantly distinguishable from configs_create, though it never names or contrasts a sibling explicitly.

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

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

The description explains what the tool returns but gives no when-to-use guidance, no prerequisites, and no alternatives for retrieving configs. An agent must infer usage entirely from the resource noun.

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 only declare the safety profile (not read-only, not destructive, not idempotent, open-world). The description adds genuinely useful behavior the annotations cannot convey: the source of launched agents (profile's current config), what gets sent on each firing, and the missed-firing coalescing rule including that only the oldest missed time fires. It omits permission/auth requirements and failure handling, so it is strong but not exhaustive.

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 sentences, front-loaded with the core action before the per-target behavior and the coalescing rule. The final sentence is long but every clause conveys distinct scheduling semantics; no filler or restated title 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?

For an 8-parameter, nested-object, open-world mutation tool with no output schema, the description covers the call's runtime effect and scheduling edge case well while annotations carry the safety profile and the schema carries parameter detail. Minor gaps remain around auth/permission requirements and the required-vs-omitted status of message_template per target type, but nothing critical 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 100%, so the schema already documents all eight parameters, including the target discriminator and message_template semantics. The description restates the target-type meanings already present in the schema and adds no new syntax, defaults, or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Creates a cron trigger that fires on a schedule') and immediately distinguishes its behavior from the sibling crons_update/delete/get/list family. It goes further by explaining what the three target types actually do on each firing, so an agent understands the effect of the call without opening the schema.

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

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

The description explains what each target type does, which implicitly guides selection of the `target` value, but it never states when to reach for crons_create versus crons_update or other trigger-management siblings, nor any prerequisites (e.g., that a profile/agent must already exist). Usage context 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description still adds two traits the annotations cannot express: irreversibility ('there is no undo') and the non-obvious side effect that already-launched agents keep running.

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

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

A single dense sentence with the irreversible consequence and the residual side effect front-loaded; nothing is wasted and nothing needed is omitted.

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

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

For a three-ID delete tool with no output schema and full annotation coverage, this is close to complete: it conveys the destructive, permanent nature and what survives. Only the absence of any routing guidance to a less drastic sibling holds it back.

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 three documented ID patterns, so the schema carries the full parameter burden. The description adds no additional meaning about the required orgID/projectID/cronTriggerID scoping.

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 (deletes) and resource (cron trigger) plus the effect ('never fires again'), which cleanly separates it from crons_create, crons_get, crons_list and crons_update without opening any schema.

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

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

No explicit when/when-not guidance and no alternative is named (e.g., whether updating or disabling is preferable). The stated effect implies a use case, but nothing helps the agent decide between this and sibling mutation 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description goes further by disclosing the exact return payload, including firing state (last_fired_at, next_fire_at) and any failure since the last successful firing — meaningful behavioral context that annotations cannot carry, and there is no output schema to do it either.

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

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

One sentence, front-loaded with the action and scope, then the returned fields. No filler or repetition.

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 getter with three fully documented parameters and no output schema, the description carries the return-value burden well by listing the payload fields. It omits edge behavior such as not-found or unauthorized responses, which is a minor gap rather than a blocker.

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%: all three required IDs carry pattern and format documentation. The description adds nothing about parameters, which is acceptable when the schema fully documents them, so the baseline 3 applies.

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

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

States a specific verb and resource ("Returns one cron trigger") and enumerates the fields it yields, which clearly separates it from crons_list. It stops short of explicitly naming the sibling alternative, but the singular scope 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?

Usage is only implied: an agent infers this is the single-item retrieval for a known cron trigger ID, with crons_list for enumeration and crons_update for changes. There is no explicit when-to-use, prerequisite, or when-not 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description only needs to add beyond that. It does add two useful traits: the default sort ('newest first') and the per-item return contents ('schedule and next_fire_at'), which is valuable since no output schema exists. Pagination behavior is left unmentioned.

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 decision-relevant facts (what is listed, default ordering, filter axes, returned fields) are front-loaded in that order.

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 9 parameters and no output schema, the description usefully covers what each item contains, which is the main gap an agent would otherwise face. It stops short of mentioning pagination/cursor usage or result counts, so it is strong but not fully complete.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema; the description's list of filter dimensions maps onto name, agent_id, agent_profile_id and integration_id but adds no syntax or format detail beyond them. Baseline 3 is appropriate when the schema carries the 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 and resource ('Lists the project's cron triggers') plus scope, default ordering, and the dimensions it can be filtered by, which is enough to separate it from crons_get and crons_create. It does not explicitly name a sibling alternative, so it falls short of the top band.

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

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

'filterable by name, agent, profile, or integration' implies when the tool is useful, and 'newest first by default' hints at the default behavior, but there is no explicit when-to-use versus crons_get or any stated prerequisite for the required orgID/projectID. Usage is left to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the mutation risk is known. The description adds genuinely new behavioral context beyond them: the target field is immutable and retargeting requires delete-and-recreate. It does not describe auth/permission requirements or partial-update semantics.

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

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

Two tight sentences, no filler, with the primary action front-loaded and the immutability caveat immediately following. Every clause earns its place.

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

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

For a mutation tool with no output schema but rich annotations and full schema coverage, the description supplies the key caveat (immutable target) an agent needs before calling. It omits which fields are optional on update and whether omitted fields are preserved, which is a minor gap given the schema documents defaults.

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 9 well-documented parameters, so the schema carries the semantic load and a baseline of 3 applies. The description reinforces the target immutability constraint, which is useful, but adds little on the other 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 gives a specific verb ('Updates') plus the updatable facets ('schedule, message template, or enabled state'), which is enough to distinguish it from crons_create and crons_delete. It is slightly incomplete against the schema, which also permits updating 'name' and 'timezone', but the core purpose is unambiguous.

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

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

It explicitly states the when-not case: 'The target is immutable; delete the trigger and create a new one to retarget.' That routes the agent to crons_delete + crons_create for retargeting. It does not spell out prerequisites or when to prefer update over recreating for other fields, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real value beyond them by disclosing the failure mode for pooled machines (404) and confirming that a grant record plus the machine record 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?

Two sentences, no filler, with the core action and its main constraint front-loaded before the edge-case behavior.

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

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

For a mutation tool with no output schema, the description covers the effect, the return content and one key error condition. It stops short of noting permission requirements or what happens on a repeat grant given idempotentHint=false, which is the remaining 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%, so the schema already documents all five parameters including format patterns and metadata limits. The description adds nothing about parameters and mildly conflicts with the schema by saying the machine is referenced 'by name' when the required parameter is machine_id (mch_...), not a name.

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 ('Lets a project's agent configs use one BYO machine'), and explicitly scopes it to BYO machines as opposed to pooled ones, which separates it from grant_pools_add and the grant_machines_* 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?

The 'Pooled machines can't be granted this way and return 404' clause gives an explicit when-not condition and implicitly routes pooled-machine grants elsewhere, but it never names the alternative tool (e.g. grant_pools_add) the way a 5 would.

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=true, so the safety profile is covered. The description adds genuinely new context beyond them: dependent processes are stopped as a side effect, the machine resource survives, and there are no dependency blockers preventing the delete. It stops short of noting permissions requirements or reversibility.

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, no filler, with the primary action stated first and consequences following. 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 destructive three-ID delete with full schema coverage and rich annotations, the description covers what is destroyed, what is preserved, and the side effects. No output schema exists and none is needed; only auth/permission expectations are absent.

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 clear patterns for grantID, orgID, and projectID, so the schema fully documents the inputs. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Removes the project's access to the machine') and immediately disambiguates from the adjacent machines_delete by noting 'The machine itself is retained.' An agent can distinguish this from grant_machines_add/list and machines_delete without opening any schema.

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

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

The purpose implies the usage context (revoking a project's machine grant), but there is no explicit when-to-use, when-not, or named alternative among the many grant_* and machines_* siblings. Guidance is inferred rather than stated.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: these grants are 'explicit' and 'can be deleted directly,' and pool-derived access is out of scope — information an agent cannot derive 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?

Two short sentences with no filler; the primary scope statement is front-loaded and the exclusion follows immediately. 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 read-only list tool with fully documented parameters, no output schema, and annotations carrying the safety profile, the description supplies the one thing the structured fields lack: the distinction between explicit and pool-derived grants. Return format and pagination are handled by the schema, so 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% across all six parameters, including glob semantics, sort enum, cursor pagination, and ID patterns, so the schema does the heavy lifting. The description adds no parameter-level detail beyond what is already documented, which is the baseline 3 case.

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 ('Lists explicit machine grants') and immediately scopes what is and isn't included by contrasting explicit grants with pool-derived access. It does not name a specific sibling tool, but the resource is unambiguous within the grant_machines_* family.

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 tells the agent the condition under which this list is the right one (explicit grants) and where the excluded case lives ('Pool-derived machine access is managed through project machine pool grants'), effectively routing the agent to the pool-grant tools. No explicit named alternative tool or prerequisites, so not a full 5.

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

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

Annotations already declare a non-read-only, non-idempotent, non-destructive mutation. The description adds genuine value beyond that: overrides can only narrow the model (lower limits, disable tools/reasoning, fewer efforts/modalities) and set per-request defaults within those limits, and it states it returns the new grant.

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 the core action first and the override behavior second. It is dense but not padded; no filler sentences.

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 13-parameter mutation tool with 92% schema coverage and no output schema, the description covers what the tool does, the narrowing semantics of the optional fields, and the return value. Gaps remain on permission requirements and duplicate/idempotency behavior, but the annotations partially cover the safety profile.

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 92%, so the baseline is 3. The description adds a useful conceptual layer by grouping the override params as narrowing-only and distinguishing model-wide limits from per-request defaults, helping the agent understand how the 10 optional fields relate rather than treating them in isolation.

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 (grant) and resource (configured model to a project) and states the outcome ('returns the new grant'). It is clearly distinguishable from grant_models_delete and grant_models_edit by name and effect, though it never names a sibling explicitly.

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

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

There is no explicit when-to-use guidance or routing to grant_models_edit/grant_models_delete, nor any prerequisites (permissions, existing grant behavior). The 'optional overrides can narrow the model' clause hints at constraints but does not tell 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?

Goes well beyond the destructiveHint/idempotentHint annotations by disclosing the live-policy effect: new launches can no longer select the model and already-running agents lose access on their next call. It also confirms the model itself is retained and that there are no dependency blockers, which is exactly the context an agent needs before a destructive call.

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

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

Three sentences, zero filler, and the effect on live policy is front-loaded right after the action statement. Every sentence carries distinct 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 destructive mutation with no output schema, the description covers what is destroyed (the grant), the scope and timing of the effect, and what is preserved, while annotations supply the safety profile. Nothing essential is left implicit.

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

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

Schema description coverage is 100% with patterns documented for all three IDs, so the schema already carries parameter semantics. The description adds no parameter-level detail (e.g. how to obtain a modelGrantID), 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 ('Removes the project's access to the configured model') and clearly separates itself from the sibling grant_models_add/edit/list family. An agent knows exactly which operation this is without opening the schema.

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

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

The description implies when this applies (revoking a project's model access) and spells out the consequence, but it never names an alternative such as grant_models_edit or a condition for choosing between them. Usage is inferable rather than stated.

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

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

Annotations already flag destructiveHint=true and non-idempotent, and the description adds substantial context beyond them: partial-update semantics (omitted fields retained), the null/[] clearing behavior for specific fields, that changes take effect on the agent's next model call, and the critical failure mode where narrowing below an agent config breaks its next call. This is exactly the behavioral disclosure an agent cannot infer from structured fields.

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 core purpose is front-loaded, followed by three dense, non-redundant sentences covering clearing semantics, propagation timing, and the failure mode. Every sentence earns its place with no filler.

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

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

For a 13-param mutation tool with no output schema, the description covers the behaviorally important edge cases: partial update, override clearing, propagation timing, and validation/failure scope. Annotations carry the safety profile, so nothing essential 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 coverage is 92%, so the baseline is 3, but the description adds meaning the schema lacks: which specific parameters support null/[] clearing (supported_reasoning_efforts, input_modalities, output_modalities) and that omission preserves current values. It does not cover the remaining params, but the added clearing semantics are the high-value ones.

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: updating the project's overrides for the configured model. The grant_models_* siblings (add/delete/list) are clearly differentiated by the 'overrides' framing, so an agent can pick this tool without opening the schema.

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

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

Explains the operational contract for omitted vs null vs [] values, which is effectively guidance on how to invoke it correctly. It does not, however, explicitly name when to prefer this over grant_models_add/delete or state exclusions, so it falls short of full when/when-not 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 establish read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real value beyond that by stating the default ordering ('most recently granted first by default') and describing what each returned grant contains, which the annotations do not convey.

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

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

A single front-loaded sentence that packs purpose, default ordering, and payload shape without waste. It is slightly dense and could be split for scannability, but 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 compensates by summarizing the return payload, and pagination/filtering are fully covered by the schema. Combined with annotations covering the safety profile, this is nearly complete; only explicit sibling routing and prerequisites are 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%, so all six parameters (including glob semantics for name and cursor pagination) are already documented in the schema, giving a baseline of 3. The description only implicitly touches the sort default and adds no syntax or format detail beyond what the schema 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?

Names a specific verb (Lists) and resource (configured models a project can use / grants), and distinguishes itself from the sibling models_list and model_providers_list by scoping to project grants. It also previews the payload (overrides, model name, provider config), so an agent can tell it apart from add/delete/edit siblings without opening schemas.

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 guidance, no exclusions, and no named alternatives (e.g., use models_list for the full catalog vs this tool for project grants). The project-scoped phrasing implies context but the agent must infer 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 establish the safety profile (non-read-only, non-destructive, non-idempotent, closed-world). The description adds real behavioral context beyond them: the grant is returned, per-project defaults and caps are bounded by the pool's own limits, and critically that no machines are materialized by the call. It stops short of stating required permissions or what happens on a duplicate grant.

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

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

A single sentence front-loads the core action, then the optional capability, then the return value, and closes with the negative constraint. No filler and nothing repeated from the schema.

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

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

For a 19-parameter mutation with nested overlays and no output schema, the description covers the high-level effect adequately and says the grant is returned. It omits prerequisites (permissions, whether a grant already existing is an error) and gives no hint that the overlays merge over pool defaults, which is left entirely to 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 100% across all 19 properties, so the schema already documents every field, including the min/max/default CPU and memory semantics. The description only gestures at these collectively as 'its own defaults and usage caps within the pool's limits', adding no syntax or precedence detail beyond the schema. Baseline 3 applies.

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

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

The description names a specific verb and resource: it grants a machine pool to a project so the project can create machines from it, and states the result (returns the grant). This clearly separates it from grant_pools_edit/delete/list and from machines_create. It does not, however, explicitly contrast itself with the closest siblings by name.

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

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

There is no when-to-use guidance and no named alternative (e.g. grant_pools_edit for changing limits, grant_pools_list for inspection). The only usage-adjacent signal is the exclusion 'No machines are created by this call', which rules out one mistaken intent but doesn't route the agent between 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?

Goes well beyond the destructiveHint/idempotentHint annotations by disclosing cascade effects: machine grants generated through the pool grant are revoked and dependent processes are stopped, while the pool itself survives. It also states there are no dependency blockers, which is exactly the risk information an agent needs before a destructive call.

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

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

Two dense sentences with zero filler; the destructive consequence is front-loaded and the reassuring non-effects (pool retained, no blockers) follow. Every clause earns its place.

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

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

For a destructive tool with an output schema absent and annotations limited to boolean hints, the description fully covers what is destroyed, what is preserved, and whether blockers exist. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% with all three IDs documented (orgID, projectID, poolGrantID with patterns), so the schema carries full parameter meaning. The description adds no additional parameter syntax or format detail, 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?

States specific verbs and resource: removes the project's access to the machine pool and revokes the associated grants. It also distinguishes itself from the sibling pools_delete by explicitly noting 'The pool itself is retained', so an agent can tell it apart without opening the schema.

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

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

The purpose is clear, but there is no explicit when-to-use or when-not guidance and no named alternative among the grant_pools_* and pools_delete siblings. Usage is implied by the tool name rather than stated.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false; the description goes well beyond that by explaining PATCH semantics (omitted fields unchanged, null clears an override and restores pool inheritance), whole-object replacement for overlays/metadata, and the key consequence that existing machines keep their config while new launches pick up the new defaults/limits. It does not cover permissions or reversibility, so it lands just short of the top.

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 tightly packed sentences, each carrying a distinct rule (scope, PATCH semantics, replacement semantics, effect on existing vs new machines), with the core action front-loaded. No filler or restatement of the tool name.

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

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

For a 19-parameter mutation with nested objects and no output schema, the description covers the hard parts: partial update semantics, inheritance clearing, and how changes propagate to machines. It is let down slightly by not mentioning authorization scope or what the call returns, but the behaviorally risky aspects are all addressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning the schema does not: the general omitted/null/cleared-override contract and the fact that overlay objects and metadata are replaced whole rather than merged. That materially improves how an agent would populate the nullable limit and overlay 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 opens with a specific verb+resource: 'Updates the grant's overrides and limits.' Combined with the tool name, an agent can immediately tell this is a mutation of an existing machine-pool grant rather than a get/list/add/delete operation, and 'overrides and limits' accurately scopes what is being edited.

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

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

The description implies this is the tool for changing an existing grant and even explains inheritance behavior relative to the pool, but it never states when to pick it over grant_pools_add/delete or grant_models_edit, nor any preconditions or exclusions. 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful semantics the annotations cannot: null fields mean no override and the pool's value applies, which shapes how the agent reads the result.

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

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

Two sentences, no filler, with the core purpose front-loaded and the override semantics placed second where it belongs. 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-shape burden; it does explain that the grant supplies defaults and limits and that nulls mean no override, which is the key interpretive fact. It stops short of enumerating the response fields, a minor gap for a read tool whose annotations already cover safety.

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 all three IDs (org_/proj_/pmpg_) documented including patterns, so the schema does the heavy lifting. The description clarifies the relationship between project, pool and grant conceptually but adds no per-parameter detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb ('Returns') and resource ('one project's grant for a machine pool'), and the word 'one' plus the singular key set distinguishes it from grant_pools_list and grant_pools_edit without opening either schema. It also conveys the semantic layer of the resource (defaults/limits on top of the pool's 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?

The singular, ID-keyed retrieval implies usage for fetching a single known grant, which is adequate for a simple getter. However, it never explicitly says when to use this versus grant_pools_list, nor mentions prerequisites such as the caller already needing the pmpg_ ID.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond structured fields: one grant per pool and default ordering most-recently-granted-first. It stops short of richer behavioral detail such as pagination or failure modes.

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 that establishes the resource and the key behavioral default with no wasted words.

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

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

With no output schema, the description conveys what is returned (one grant per pool) and the default ordering, which covers the essentials for a list tool. It omits detail about the shape of a grant record, but the sibling grant_pools_get covers that.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters (name glob, sort enum, limit, cursor, IDs). The description adds no parameter-level detail, which is the correct baseline when the schema does the heavy lifting.

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

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

The description states a specific verb (Lists) and resource (machine pool grants a project can create machines from), which is clear enough to separate it from grant_pools_add/get/delete. It does not explicitly name those siblings, but the semantics of 'grant' vs 'get' is discernible.

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 list-nature of the endpoint, but there is no explicit when-to-use or when-not-to-use guidance, nor any pointer to grant_pools_get for a single grant. The default ordering note hints at default behavior but not 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds genuinely useful context beyond them: 'ownership doesn't change' clarifies this is a non-transferring share, and 'returns the grant' discloses the response. It stops short of covering re-grant/idempotency behavior or required permissions.

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

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

One sentence, front-loaded with the action and recipient, with the two most important caveats (resource usability, ownership unchanged) packed into the same sentence. 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?

For a three-required-param mutation with no output schema, the description covers the action, the effect on the target project, the ownership invariant, and the return value. It omits permission requirements and duplicate/repeat-grant behavior, which keeps it just short of fully complete.

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

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

Schema description coverage is 100%: all three parameters carry format descriptions and patterns (org_..., sec_..., proj_...). The description adds no parameter-level detail, so the baseline 3 is appropriate.

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

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

The description states a specific verb (shares/grants), the resource (a secret), and the target (another project), plus the consequence (that project's resources can use it). It is clearly distinguishable from grant_secrets_delete and grant_secrets_list by verb alone, though it never explicitly names those siblings.

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

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

The clause 'so that project's resources can use it' gives an implied use context, but there is no explicit guidance on when to prefer this over alternatives or on prerequisites (e.g., admin permissions, whether the target project must exist). Usage is inferable but not stated.

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

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

Goes well beyond the annotations: it specifies the exact blast radius (only the grant is removed) and what survives (secret, its versions, target project, other grants), and rules out dependency blockers. This is the kind of destructive-operation detail an agent needs before calling a delete that annotations alone (destructiveHint/idempotentHint) cannot convey.

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

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

A single tight sentence, front-loaded with the verb and the object and immediately qualified by scope and retention. Zero 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?

For a destructive 3-param delete with no output schema, the description covers scope, retention, and absence of blockers, which is nearly all an agent needs. A note on authorization/permissions would make it fully complete.

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

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

Schema coverage is 100% with each of the three IDs documented, including format patterns, so the schema does the heavy lifting. The description adds no parameter-level detail (e.g., cross-org semantics), so baseline 3 applies.

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

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

States a specific verb (Deletes) and resource (project grant), and the word 'only' plus the enumeration of what is retained (secret, versions, target project, other grants) distinguishes it from grant_secrets_add/list and secrets_delete. It does not explicitly name those siblings, 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?

The description gives clear context for the operation by clarifying scoping (deletes only the grant) and confirming there are no blockers, implying it is safe to invoke without dependency resolution. It does not explicitly state when to prefer it over revoking access another way, but the implied usage is unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered and the bar is lower. The description still adds genuine behavioral context not present in the annotations: the return cardinality (one grant per project) and the default ordering (most recently shared first), which the schema's sort enum does not state as a default.

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 well-formed sentence with the key facts front-loaded (what it lists, granularity, default ordering) and no filler. It is efficient, though for a six-parameter paginated list it is arguably too sparse to fully carry its load.

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 states what is returned (one grant per project) and the default ordering, which an agent needs to interpret results correctly. Pagination behavior is left to the schema's cursor parameter, so nothing critical is missing, but the description does not tie the pieces together.

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

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

Schema description coverage is 100%, so every parameter (name glob, sort, limit, cursor, orgID, secretID) is already fully documented in the schema. The description adds no parameter-level syntax or constraint beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (Lists) and resource (the projects a secret is shared with), and clarifies the granularity ('one grant per project'), which distinguishes it from grant_secrets_add/delete. However, it never names or contrasts itself with the sibling grant lists (machines/models/pools/skills), so sibling differentiation is left implicit.

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

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

The phrase 'most recently shared first by default' implies the sort parameter can override ordering, but there is no explicit when-to-use guidance, no statement of when to prefer this over the other grant_*_list tools, and no note on pagination handling. 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 destructiveHint=false and readOnlyHint=false, so the safety profile is covered; the description adds genuine context beyond them by noting that ownership does not change and that the grant is returned. It stops short of warning that idempotentHint=false means repeat calls create additional grants, which would have made this a 5.

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

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

A single sentence that front-loads the action and packs the target, the downstream effect and the ownership invariant without filler. Every clause earns its place.

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

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

For a three-parameter mutation with no output schema, the description usefully notes that it returns the grant and that ownership is unaffected. It leaves out any permission or authorization prerequisite for granting a skill across projects, which is the one meaningful gap.

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

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

Schema description coverage is 100%, with orgID, skillID and target_project_id each documented with format hints, so the schema carries the parameter burden. The description adds no syntax, format or selection detail beyond what the schema already provides, 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 states a specific verb ('shares a skill'), the resource (a skill) and the scope (with another project), plus the effect ('so its agent configs can attach it'). It is trivially distinguishable from its siblings grant_skills_delete and grant_skills_list, whose names already mark the differing operations.

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 rather than stated: the agent can infer this is the tool for making a skill attachable by another project's agent configs. There is no explicit when-to-use framing, no when-not-to-use clause, and no reference to grant_skills_list or grant_skills_delete as alternatives.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety is covered structurally. The description adds genuine value beyond them: an explicit blast radius (skill, revisions, target project and other grants are retained) and the guarantee of "no dependency blockers", which tells the agent the call should succeed cleanly.

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

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

Two sentences, no filler, and the destructive scope is front-loaded in the first clause. 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?

With rich annotations and fully documented parameters, the description only needs to convey scope and side effects, which it does. It does not address failure modes (e.g. grant not found) but no output schema exists, so return-value coverage is not required.

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 each of the three required IDs carries its own format pattern and description. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb ("Deletes") and a narrowly scoped resource ("only this project grant"), which implicitly distinguishes it from skills_delete by making clear the skill itself is untouched. It stops short of naming grant_skills_add or grant_skills_list, so the routing is inferable rather than explicit.

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

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

There is no when-to-use statement, no prerequisites (e.g. required permissions), and no named alternative. Usage is only implied by the scope constraint that the skill and other grants survive, which an agent must interpret on its own.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful behavioral context — one grant per project and the default ordering — but says nothing about pagination or the structure of a grant. With annotations carrying safety, 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 tightly written sentence that front-loads the resource and then the notable behavioral detail. It is appropriately sized and wastes no words, though it is short enough to leave a little room unexploited.

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 rich annotations and full schema coverage, the safety and parameter story is handled elsewhere, and the description covers cardinality and ordering. However, with no output schema it does not describe what a grant actually contains (e.g. permissions or scope), leaving that gap unfilled.

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

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

Schema description coverage is 100%, so all six parameters are already documented. The only value the description adds is the default sort order ('most recently shared first'), which the generic sort enum description does not state. That is a marginal addition over the schema, so baseline 3 holds.

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: 'Lists the projects a skill is shared with', which is precisely what a skill grant is. It distinguishes this read operation from the grant_skills_add/delete siblings by implication, though it never names them. Clear purpose, but no explicit 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 by the resource name (you call it when you need to see where a skill is shared), and 'most recently shared first by default' hints at default behavior. However, there is no explicit when-to-use guidance, no when-not, and no named alternatives such as grant_skills_add.

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 (write, non-idempotent, non-destructive), the description discloses critical behavior: the daemon token is returned and 'shown only in this response' (one-time secret visibility), the machine 'stays offline until its daemon connects', and project_ids grants the machine to projects in the same call. These are non-obvious traits that directly affect how an agent should handle the result.

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

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

The definition is front-loaded with the core action and what it returns, and every clause carries information. It is somewhat dense with semicolon-chained clauses, but nothing is filler and the most important fact (one-time token) appears early.

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 correctly explains the return (a one-time daemon token). For a 9-parameter tool with nested objects, it covers the critical behaviors and the non-obvious project_ids/display_name linkage; remaining parameter details (cwd, env, secret_env, metadata) are well documented 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 100%, so the baseline is 3, but the description adds meaning beyond the schema for project_ids (granting projects in the same call) and the display_name relationship ('their agent configs reference it by display_name'), which is not stated in the schema. It adds real value without covering every parameter.

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

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

The description states a specific verb and resource ('Registers a machine you run yourself') and immediately clarifies the BYO nature versus the pool/provisioning siblings. It also tells the agent what the call produces (a daemon token for installing omnarad). An agent can distinguish it from machines_update, machines_get, and pools_create without opening any schema.

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

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

'Registers a machine you run yourself' implies the BYO use case versus pool-provisioned machines, but no explicit when-to-use/when-not or named alternative is given. The project_ids note describes an in-call side effect rather than routing guidance. Usage context is present but must be inferred.

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 idempotentHint=true, so the description goes further by enumerating the concrete side effects: ending daemon runtimes and work, revoking daemon tokens and project grants, and releasing agent bindings. This is rich behavioral context beyond what annotations provide.

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 dense sentences, each earning its place: the scope of what is deleted, the exclusion for pooled machines, and the dependency note. No waste and front-loaded with the core action.

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 two-parameter mutation tool with full schema coverage and annotations covering the safety profile, the description supplies the missing piece: the cascade of side effects and the applicability boundary. Nothing an agent needs to call this correctly is absent.

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

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

Schema description coverage is 100%, so the schema already documents both machineID and orgID with their patterns. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Deletes a BYO machine') and immediately distinguishes this tool from the machines_delete route for pooled machines, routing the agent to the machine pool instead. This differentiation from related tools is exactly what an agent needs.

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

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

It explicitly states when this tool applies (BYO machines) and when it does not (pooled machines, which go through their machine pool), plus notes there are no dependency blockers. This is clear when-to-use/when-not-to-use 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 readOnly/idempotent/non-destructive/closed-world, and the description adds real value on top: secrets are surfaced as IDs and never values (a privacy guarantee), the latest failure report is included, and non-active lifecycle states are excluded from results. It stops short of saying what happens when the target machine isn't active (error vs empty).

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

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

Two tight sentences, zero filler, with the returned payload front-loaded and the scoping caveat following as a qualifier.

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's enumeration of returned fields does the necessary work and covers the important non-obvious one (secret IDs, not values). The only gap is failure behavior for a non-active or nonexistent machine, which an agent must guess.

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 required parameters (orgID, machineID) carry their own patterns and descriptions, so the schema fully carries parameter semantics. The description adds no syntax or constraint detail beyond that, making the baseline 3 correct.

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 ('Returns one active machine's full record') and enumerates the payload: connection state, execution defaults, metadata, latest failure report. The singular 'one machine' plus the active-only scope cleanly separates it from machines_list without needing to name the 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?

The description implies when this is appropriate by limiting results to active machines, and notes that provisioning/pool machines won't come back. However, it never names an alternative (e.g. machines_list to discover IDs, or how to inspect non-active machines), so the agent must infer routing from context 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/non-destructive, but the description goes further by disclosing the default sort ('newest first') and, importantly, that items are summaries lacking execution defaults or metadata - a real expectation-setting detail since there is no output schema. It does not discuss pagination behavior beyond what the cursor param 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?

Two tight sentences with no filler; scope and default ordering are front-loaded and the payload caveat closes it out. Every clause earns its place.

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

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

With no output schema, the description compensates by describing what each item contains (summary plus connection state, omitted execution defaults/metadata) and the default ordering. Missing only pagination/return-envelope detail, which is minor given the cursor parameter.

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

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

Schema description coverage is 100%, so every parameter (name glob, sort, limit, cursor, source_kind, machine_pool_id, orgID) is already documented in the schema. The description only echoes the source_kind default ('both BYO and pooled') and the sort default, adding little beyond structured fields.

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

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

States a specific verb+resource (lists machines) plus scope (the caller can see), coverage (BYO and pooled), default ordering, and the payload trait (connection state). An agent can distinguish it from machines_get and machines_create by the verb, though it never names a sibling explicitly.

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

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

There is no guidance on when to reach for this versus machines_get for a single machine, or grant_machines_list for permission-scoped listings. Usage is only implied by 'lists ... the caller can see'; no exclusions or alternatives are offered.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond the annotations: env and secret_env replace the whole map (not merge), and changes only affect processes started afterward. It does not mention auth/permission requirements, keeping it from 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?

Two tight sentences, front-loaded with what is updated and then the two highest-risk behavioral facts (replace semantics, propagation timing). 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?

For a 5-parameter mutation tool with nested objects, no output schema, and annotations covering safety, the description supplies the critical replace-semantics and timing details. It omits permission requirements and behavior of omitted fields (e.g. whether cwd is unchanged when not passed), so it is not fully complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: env and secret_env are whole-map replacements rather than merges, and the update is scoped to future processes. cwd and the ID parameters are left 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 (updates) and resource (a machine's execution defaults) and enumerates the affected fields (cwd, env, secret_env). It is clear enough to distinguish from machines_create/delete/get/list, though it does not explicitly name or contrast those siblings.

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

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

There is no guidance on when to use this tool versus alternatives, nor any prerequisites (required orgID/machineID, permission or grant requirements). The sentence about changes applying to later processes is behavioral, not usage-routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely useful behavior beyond that — it validates credentials, waits on the upstream provider (latency warning), and can surface upstream failure as ordinary data rather than an error. That failure-as-data disclosure is exactly the kind of gotcha an agent needs.

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

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

Two sentences with zero waste: the first front-loads what the tool does and how, the second adds the behavioral caveats (slowness, failure-as-data). No filler or restatement of the name.

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

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

With annotations covering the safety profile and the description covering latency and the failure-as-data return behavior, an agent has what it needs to call this correctly despite the absence of an output schema. Return structure is left implicit, but the main return gotcha is flagged.

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 required parameters are fully described with ID patterns, so the schema carries the parameter burden. The description adds only the loose implication that modelProviderConfigID holds the credential being validated — no syntax or format beyond the schema, matching the baseline 3.

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

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

States a specific verb and resource — "Fetches the provider's live model catalog" — and distinguishes itself from the sibling config routes by revealing the mechanism: validating the configured credential and probing /models. An agent can tell this apart from model_providers_get/list without opening either schema.

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

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

It positions itself against "the other model provider config routes" and flags that it is slower, which implies when it is and isn't the right choice (live data vs. cheap config reads). It stops short of naming a specific alternative (e.g. model_providers_get or models_list) or an explicit when-not-to-use condition, so it is clear context rather than full routing guidance.

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

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

Annotations only declare the mutation profile (readOnly=false, destructive=false, idempotent=false); the description adds real behavioral detail beyond that: credential validation against the provider's validation endpoint, a probe of /models, and the important guarantee that a failed probe does not fail creation. It stops short of covering auth/permission requirements or what happens on partial failure.

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

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

Two tightly packed sentences with zero filler; the creation act is front-loaded and the failure-tolerance caveat is placed last, where it matters most.

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 14-parameter, nested-object mutation with no output schema, the description usefully names the return artifact (model_catalog) and discloses the validation/probe side effects. It omits credential/permission prerequisites and any pointer to the update path, but the core call-time behavior is covered.

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

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

Schema description coverage is 100%, so every one of the 14 parameters is already documented, including the preset's role in filling api_format/base_url/auth_kind. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Create a model provider config') and distinguishes itself from sibling mutations by describing the creation-time validation and probing sequence. An agent can tell this apart from model_providers_update or model_providers_catalog without opening any schema.

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

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

It implies when creation is appropriate by enumerating what creation entails, but never names alternatives (e.g. model_providers_update for existing configs) or states preconditions such as needing an existing credential secret and orgID. Usage is inferable but not spelled out.

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=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds genuinely useful preconditions the annotations cannot convey — the configured-models block and the cluster-managed restriction — which is real added value, though it doesn't describe failure response or how to resolve the block.

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, no filler, with the core action front-loaded ahead of the two constraints. Efficient, though the constraints could be tightened into a single clause.

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 delete with no output schema, the description covers the key risk: when the call will fail. Return/error format is not addressed, but with annotations carrying the destructive/idempotent profile, an agent has what it needs to decide whether to invoke.

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?

Both parameters are fully documented in the schema (100% coverage) with patterns and prefix conventions. The description adds no additional parameter 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?

States a specific verb and resource ('Deletes ... the model provider config') and the qualifier 'only' signals that associated models are not removed, implicitly distinguishing it from siblings like models_delete. The distinction is implied rather than named explicitly, so it falls just 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?

Gives clear when-not conditions: deletion is blocked while configured models exist, and cluster-managed provider configs cannot be deleted through this route. It does not name an alternative route or tool for those blocked cases, so guidance is clear but not fully 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds two non-obvious traits: secrets are redacted from the response and the provider is not contacted, so models will be absent. It does not mention error behavior for invalid/missing IDs, which keeps it short of a 5.

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

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

Two tight sentences with no filler, front-loaded with what is returned before the caveats about what is omitted. 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?

With no output schema, the description does the important work of telling the agent what will and will not appear in the response (no secrets, no models). It stops short of sketching the remaining returned fields or failure modes, which for a two-parameter read tool is 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% and both parameters carry their own format pattern documentation, so the schema does the work. The description adds no meaning about modelProviderConfigID or orgID beyond what the schema states.

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

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

States a specific verb and resource ('Returns one model provider config's stored settings') and the singular scope distinguishes it from the sibling model_providers_list. An agent can pick it out of the six model_providers_* tools without opening any schema.

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

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

The singular 'one ... config' implies the fetch-by-ID use case, but the description never states when to use this versus model_providers_list or model_providers_catalog, nor any prerequisites such as needing a valid org-scoped ID. Usage is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral fact not in annotations: filtering, sorting, and pagination are performed server-side rather than client-side. It stops short of describing return shape or paging edge behavior.

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

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

A single front-loaded sentence with no wasted words; the capability list is compact and immediately readable. It is perhaps too terse to be a 5, since it trades away any differentiating or routing detail for brevity.

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, org-scoped listing tool with full schema coverage and annotations covering safety, the description supplies enough context to invoke it correctly. The absence of an output schema is a minor gap, but listing return shape is predictable and next_cursor is already described in the cursor parameter.

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 each of the five parameters is documented in detail (glob syntax, sort enum, cursor, limit), so the schema carries the burden. The description only generically echoes filtering/sorting/pagination without adding syntax or constraints beyond the schema, matching the baseline 3.

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

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

States a specific verb (List) and resource (model provider configs) and enumerates the capabilities (filtering, sorting, pagination). It is clearly a collection endpoint rather than a single-resource get/create, though it doesn't explicitly name sibling tools like model_providers_get or model_providers_catalog for contrast.

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

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

The listing intent is implied clearly by the name and description, and 'cursor pagination' hints at how to page. However, there is no explicit when-to-use guidance versus model_providers_get or models_list, and no statement of prerequisites beyond the schema's required orgID.

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?

Goes meaningfully beyond the annotations: it discloses partial-update semantics (omitted fields retain values), the validation boundary (credential must exist and match auth_kind but the provider is never contacted), and that the updated config is returned. It does not explain the destructiveHint=true behavior the annotations imply—that headers and secret_headers are replaced wholesale—nor any auth/permission requirements, so it is strong but incomplete.

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

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

Two compact sentences, front-loaded with the action, and the second sentence earns its place by flagging the validation caveat. No filler, though 'such as its credential and headers' is slightly redundant given the schema enumerates the fields.

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 an 11-parameter mutation with nested objects and no output schema, the description covers the update semantics, validation scope, and return value adequately. It leaves out the wholesale replacement of headers/secret_headers and any permission or idempotency context, which matters given destructiveHint=true.

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

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

Schema description coverage is 100%, so the per-parameter meaning (base_url, auth_kind, auth_options, timeouts, secret_headers) is already documented in the schema. The description adds only the cross-cutting partial-update rule, not parameter-level syntax, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource with scope: it updates a model provider config's connection settings (credential, headers) and returns the updated config. The verb cleanly separates it from model_providers_create/get/delete by name, but the description itself never names a sibling or draws an explicit boundary, so it stops short of a 5.

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

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

Usage is only implied by the word 'Updates' plus the partial-update note ('omitted fields keep their values'). There is no explicit when-to-use guidance, no statement of required org permissions/setup, and no routing to alternatives such as model_providers_create or model_providers_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=false, idempotentHint=false, and destructiveHint=false. The description adds genuine behavioral context beyond them: the slug is NOT validated against the provider's catalog, and the new model is not yet usable by any project (implying further grants/config are needed). It also notes it returns the created model.

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

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

Two tight sentences with the core verb+resource front-loaded and the two important caveats (no catalog validation, not yet usable) trailing. Every clause carries information; 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 15-parameter mutation with a nested object and no output schema, the description is compact but covers the key behavioral consequences, and the schema carries full parameter detail. What is thin is return-value description ('returns it') in the absence of an output schema, plus no mention of required permissions.

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

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

Schema description coverage is 100%, so every one of the 15 parameters is already documented in the schema. The description adds no parameter-level detail (e.g., about context_window_tokens or api_variant_options) beyond what the schema provides, so baseline 3 is correct.

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

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

The description gives a specific verb and resource ('Adds a provider model to this provider config') and clarifies the naming role ('the name agent configs use as model.name'). It implicitly separates this from model_providers_create (which creates the config itself) and models_update, though it never names a sibling explicitly.

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

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

Usage is only implied: the model is added 'to this provider config,' so a provider config must already exist. There is no explicit statement of when to choose this tool over model_providers_create or models_update, and no exclusions are given.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond the annotations: the active-project-grant blocking rule and the cluster-managed exclusion. It does not describe the return value or error behavior, keeping it at 4.

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 with the core action front-loaded and constraints following. No filler or repetition. Slightly terse on the exclusion clause, but 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?

No output schema exists, but the description needn't explain return values; it does cover the destructive nature, the blocking precondition, and the route limitation, which are the key facts for a delete tool. Missing only error/response behavior, which is minor here.

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 orgID, configuredModelID, and modelProviderConfigID each documented in the schema, so the baseline is 3 per the rules. The description references the configured model but adds no parameter-level format or relationship detail beyond what the schema 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?

States a specific verb and resource: 'Deletes only the configured model.' This distinguishes it from siblings like models_update, models_create, and models_list, though it does not explicitly name any sibling. The 'only the configured model' phrasing clarifies scope but is slightly ambiguous about what else might exist.

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 concrete conditions that govern usage: deletion is blocked while active project grants exist, and cluster-managed configured models cannot be deleted through this route. These are meaningful preconditions an agent needs. No alternative tool is named, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuine context beyond that: the newest-first ordering and the per-item payload (slug, token limits, reasoning support), which matters because there is no output schema. Pagination behavior is left to the schema rather than described.

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; ordering, scope, and returned fields are packed in without 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?

With full schema coverage, no output schema, and annotations carrying the safety profile, the description supplies the return-field content the agent otherwise could not know. Pagination is deferred entirely to the schema, which is a minor gap rather than a missing requirement.

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

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

Schema description coverage is 100%, so limit, cursor, orgID, and modelProviderConfigID are fully documented structurally. The description adds only the implicit notion that results are scoped to one provider config; it does not clarify cursor/limit semantics beyond the schema, so the baseline 3 applies.

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