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 the non-obvious behavioral fact that a user approval gate applies before the fetch executes, which is real context beyond the structured fields. It omits return size or rate-limit behavior, keeping it at a 4 rather than 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, with the scope of the fetched payload front-loaded and the approval constraint at the end. Nothing needs to be trimmed.

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 enumerates what comes back (.gs/.html files plus the manifest), which is exactly the return-value context an agent needs. The only gap is that 'script_id' provenance and any payload-size caveats remain unaddressed.

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

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

Schema coverage is 50%: 'reason' is documented in the schema, but 'script_id' has no schema description and the tool description supplies no format, origin, or syntax for it. Since coverage is at best half, the description should have compensated and does not.

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

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

Names a specific verb (Fetch) and resource (Google Apps Script project source) and pins down the scope precisely: 'every file (.gs/.html) plus the appsscript.json manifest.' This clearly separates it from siblings like apps_script_list_projects and apps_script_write_content.

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 states a prerequisite ('Requires user approval') but never says when to reach for this tool versus apps_script_list_projects or apps_script_get_execution_log. Usage is only implied by the name and scope, so it is minimum-viable 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 safety is covered. The description adds value beyond them: it discloses the approval requirement ('Requires user approval') and clarifies the data is post-hoc run results rather than a streaming log.

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 that front-loads the core action and appends the exclusion and the approval prerequisite. No filler, though the em-dash clause could be read as cramming three ideas together.

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 enumerates return fields (status, duration, function). It also flags the approval workflow. But it leaves two of three parameters undocumented, which is a real gap for a 3-param 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 only 33%: script_id and max_results have no descriptions in either schema or prose. The description does not compensate for these gaps, leaving the meaning of max_results (default 10, presumably truncating runs) unstated.

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

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

States a specific verb and resource (read the result of recent script runs) with scope qualifiers (status, duration, which function ran). It distinguishes itself from a live console.log transcript and implicitly from apps_script_get_content, though it doesn't name siblings 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?

Constrains usage to scripts 'the user triggered themselves outside PrivacyFence' and clarifies it is 'not a live console.log transcript,' which steers the agent away from a wrong assumption. It stops short of naming an alternative tool for live transcripts or for source inspection.

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 structurally. The description adds useful non-structured context ('Auto-approved', container-bound exclusion), but says nothing about pagination behavior, result limits, or ordering despite a max_results 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?

Three short sentences with the primary purpose front-loaded and no filler. Efficient, though the trailing 'Auto-approved' is a fragment that sits slightly apart from the scoping content.

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

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

With no output schema, the description helpfully enumerates returned fields (id, name, last-modified time) and states the scope boundary. The remaining gap is pagination/limit semantics around max_results, which is minor for a simple list operation.

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

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

Schema description coverage is only 50%: 'reason' is documented in the schema, but 'max_results' has only a type and default with no description. The description supplies no parameter meaning at all, so it fails to compensate for the coverage gap.

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

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

Specific verb 'List' plus resource 'standalone Google Apps Script projects', and it explicitly delimits scope by excluding container-bound scripts. An agent can distinguish this from apps_script_get_content or apps_script_get_execution_log 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 exclusion of container-bound scripts clearly defines when this tool applies versus when it does not, and 'Auto-approved' signals it can be called freely. It stops short of naming an alternative tool for container-bound cases, so it is strong context but not full routing.

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

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

With annotations present the bar is lower, but the description adds substantial context the annotations do not carry: full-file replacement semantics (no partial update), the approval requirement, and the fact that the script is not executed by PrivacyFence. The only tension is that destructiveHint=false sits awkwardly beside 'replaces the project's entire file set', though the description's explicit warning makes the overwrite behavior transparent rather than hidden.

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

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

Four sentences, each load-bearing: action, replacement semantics, workflow alternative, then approval/execution caveats. The destructive-ish constraint is front-loaded before the recovery guidance, so an agent that stops reading early still sees the critical rule.

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 no-output-schema mutation tool with 3 required params, the description covers what the write does, what it clobbers, and the approval gate. It does not say what a successful response looks like or how failures surface, which is a minor remaining gap rather than a blocking one.

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

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

Schema coverage is 67% and the schema already documents files and reason, while script_id is bare. The description compensates for the most consequential parameter (files) by explaining that the passed set is the complete post-write state, not a delta, which is meaningfully more than the schema's per-entry format description.

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

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

States a specific verb and resource ('Write new source to a Google Apps Script project') and immediately constrains the scope of that write ('Replaces the project's entire file set -- there is no single-file/partial update'). This clearly distinguishes it from the sibling apps_script_get_content, which it names as the read-side counterpart.

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

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

Explicitly tells the agent when and how to use it ('always pass every file the project should have afterward, not just the ones you changed') and names the alternative workflow ('fetch the current set with apps_script_get_content first if you need to preserve files'). It also states the operational precondition ('Requires user approval') and the downstream limitation ('PrivacyFence never runs the script; the user runs it themselves').

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 is a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond annotations: the call is gated on user approval. It omits other meaningful side effects such as attendee invitations and room bookings.

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

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

Two short sentences with the operation front-loaded and zero filler. It is efficient, though arguably terse for a 12-parameter mutating tool.

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

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

For a creation tool with 12 parameters, no output schema, and partial annotation coverage, the description leaves out critical context: attendee notification behavior, room booking effects, timezone/format expectations, and recurrence handling. It is not adequate for the tool's complexity.

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

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

The description adds no parameter meaning at all. With only 67% schema coverage, several parameters (title, location, calendar_id, description) are undocumented in both places, and the description does nothing to compensate for that gap.

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

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

States a specific verb and resource ('Create a new calendar event'), so the agent knows exactly what operation this performs. It does not distinguish itself from near-siblings such as calendar_create_out_of_office or calendar_update_event, 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?

'Requires user approval' is a prerequisite, not guidance on when to choose this tool over alternatives. There is no mention of when to use create vs. update_event, or when create_out_of_office is the better choice for OOO blocks.

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 say readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds the real behavioral payload: new conflicting invitations are auto-declined while in effect, existing ones are untouched, and user approval is required. Non-idempotency and what happens on overlapping/repeated calls are not disclosed, keeping it short of 5.

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

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

Three tight sentences with no filler: the action is front-loaded, then the side effect, then the precondition. Every clause carries information an agent needs.

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

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

For a mutation tool with no output schema, the description covers the important side effect and approval requirement. It omits edge behavior such as duplicate OOO events or what the call returns, which would be needed for full completeness.

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

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

Schema coverage is 80%, so the schema already documents start_time, end_time, reason, and decline_message. The description contributes no parameter guidance (e.g., default title, decline_message 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.

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

States a specific verb and resource ('Create an out-of-office event on the primary calendar'), which is enough to separate it from the generic calendar_create_event sibling. It doesn't explicitly name or contrast with that sibling, so 4 rather than 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 an implicit frame (OOO blocks with auto-decline) plus one hard precondition, 'Requires user approval,' which is genuinely useful. However, it never says when to prefer this over calendar_create_event or what to do if an OOO event already exists, so guidance stays 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=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: what each scope value destroys ('following' keeps earlier occurrences, deletes this and every later one) and that user approval is required. It stops short of covering notification side effects tied to send_updates.

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

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

Front-loaded with the action, then the scope semantics, then the approval requirement. Every sentence carries information, though the parenthetical scope enumeration is dense against a 60%-covered 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 destructive mutation with annotations covering safety and no output schema, the description supplies the two things an agent most needs: what scope deletes and that approval is required. The gap is the unmentioned send_updates notification behavior, which affects a real side effect for a cancellation.

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

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

Schema coverage is 60%. The description meaningfully extends the 'scope' enum by explaining the semantics of 'following' and 'all', which the schema only names. However, it never mentions send_updates or the required 'reason' parameter, so it does not compensate for the uncovered half.

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 ('Delete a calendar event') and immediately disambiguates the only nontrivial dimension, recurring-event scope. An agent can tell this apart from calendar_update_event or calendar_get_event_details 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 details how to use the 'scope' parameter for recurring events but gives no explicit when-to-use vs alternatives (e.g. update vs delete, or which sibling handles series cancellation) and no prerequisites beyond 'requires user approval'. Usage is implied by the semantics 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by disclosing that user approval is required and by noting the downstream pattern of feeding each attachment's file_id into drive_get_file_content, which an agent would not otherwise know.

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

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

Front-loaded with the core action and result set, followed by attachment specifics, an integration hint, and the approval requirement. Efficient, though the parenthetical example is slightly verbose. No wasted 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?

With no output schema, the description usefully enumerates the returned fields (attendees, description, links, attachments) and even explains the downstream use of attachment file_ids, which compensates for the missing output schema. The remaining gap is the undocumented calendar_id/event_id parameters, which is captured under parameter semantics.

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

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

Schema coverage is only 33% (only 'reason' is documented), and the description supplies no meaning for calendar_id or event_id — no format, ID source, or how to obtain them. With low coverage the description should compensate, but it addresses none of the parameters, so it fails the bar for this dimension.

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 (Fetch) and resource (full details of a calendar event) and enumerates exactly what is retrieved: attendees, description, conferencing links, and attachments. This clearly distinguishes it from the listing sibling calendar_list_events, which returns summaries rather than full detail.

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

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

The description implies usage (fetches detail beyond a listing) but never states when to prefer this over calendar_list_events or calendar_get_event_visibility. 'Requires user approval' is useful context but is not a when-to-use rule. Usage is inferable, not 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 and destructiveHint=false, so the safety profile is covered. The description adds the 'Auto-approved' trait and the explicit contrast with the detail-fetching sibling, both of which are context beyond the structured fields, though it says nothing about return format or latency.

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

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

Two sentences, front-loaded with the action and value domain, followed by the differentiator. 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?

There is no output schema, but the description tells the agent exactly what comes back (the four visibility values), how it differs from calendar_get_event_details, and that it is auto-approved. The only real gap is the undocumented calendar_id/event_id parameters.

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

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

Schema description coverage is only 33% – only 'reason' is documented in the schema, while calendar_id and event_id have no descriptions. The description adds no information about any of the three parameters, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Get a calendar event's visibility setting') and enumerates the exact value domain (default, public, private, confidential). It explicitly distinguishes itself from the sibling calendar_get_event_details, so an agent can route correctly 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 clearly signals the selecting condition: use this when you only need visibility rather than full details, and names calendar_get_event_details as the heavier alternative. It stops short of stating when-not to use it or any prerequisite beyond that contrast.

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), and the description adds genuine behavioral context beyond that: the access-dependent fallback between full event details and free/busy slots, plus an 'auto-approved' note relevant to the approval workflow. It does not describe result shape or rate limits, but the added fallback semantics are substantive.

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

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

Three tightly written sentences, front-loaded with the core purpose before the fallback nuance and usage note. Every sentence carries information, though the fallback clause is dense. No padding or repetition of the schema.

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

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

For a read-only query tool with full annotation coverage, full schema coverage and no output schema, the description supplies the access-dependent return behavior an agent would otherwise have to guess, which is the main gap it needed to close. Only minor omissions (result shape specifics, pagination) remain.

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

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

Schema description coverage is 100%, so all four parameters (emails, time_min, time_max, reason) are already documented in the schema. The description references emails and a time range generically but adds no format or interpretation detail beyond the schema. 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 and resource ('Query colleagues' schedules for a time range') and scopes it to colleagues rather than the user's own calendar, which is the key distinction from siblings like calendar_list_events and calendar_get_event_details. An agent can identify what it does without opening the schema.

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

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

Provides the intended context ('Use this for meeting scheduling') but gives no when-not guidance and never names an alternative tool for related lookups (e.g., calendar_get_event_details, calendar_get_event_visibility). Usage is implied rather than contrasted.

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, covering the safety profile. The description's 'Auto-approved' adds a behavioral hint that the call skips human approval, which is context beyond the annotations, but it is unexplained and no return format or pagination behavior is 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?

Two short sentences, front-loaded with the actual operation. Nothing is padded, though 'Auto-approved' is vague enough that it slightly under-delivers for the space it takes.

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

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

For a simple read-only list tool with full schema coverage and annotations covering safety, this is close to sufficient. No output schema exists, so return values needn't be explained, but the unexplained 'Auto-approved' is a small loose end.

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

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

There is one parameter ('reason'), and schema coverage is 100%, so the schema fully documents its purpose. The description adds nothing about the parameter, which is acceptable given full schema coverage — 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+resource ('List all Google Calendars') with a clear scope qualifier ('for the authenticated user'). It implicitly distinguishes itself from sibling list tools like calendar_list_events, calendar_list_rooms, and calendar_list_colors by naming the distinct resource, though it never names those siblings directly.

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

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

No guidance on when to use this vs. alternatives or what a caller should do with the result. The trailing 'Auto-approved' is a cryptic note rather than usage direction. With over a hundred sibling tools, some routing context would be valuable.

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 structurally. The description adds genuine context beyond that: the palette is 'fixed' (safe to treat as static/cacheable) and the call is 'Auto-approved', which matters in a toolset that otherwise contains privacyfence approval workflows.

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: what it returns, when to use it, and a note on approval. The most decision-relevant information (use this instead of guessing an id) is front-loaded and there is 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?

No output schema exists, but the description enumerates the returned fields (id, name, hex background/foreground), giving examples of names. For a simple read-only enumeration tool this covers everything an agent needs to call it and use the result.

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

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

With a single parameter and 100% schema description coverage, the schema already documents 'reason' fully, so the baseline for a one-param tool is high. The description adds no further detail about the argument, but none is needed.

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

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

States a specific verb and resource ('List Calendar's fixed event color palette') and spells out the returned fields (id, name, hex background/foreground). An agent can distinguish it from sibling list tools like calendar_list_rooms or calendar_list_calendars 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?

Explicitly tells the agent when to call it: before passing a color to calendar_create_event, calendar_update_event, or calendar_set_event_color, and why ('instead of guessing a numeric id'). This names the downstream tools and the failure mode it prevents, so no inference is needed.

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 behavior, so the bar is lower. The description still adds context beyond them: it names the exact output field subset (no attendees, description, or links) and discloses that calls are auto-approved, which is policy information the annotations do not 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 short sentences, front-loaded with the core action and no filler. It could arguably merge the output-scope note more tightly, but every sentence carries information.

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

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

For a 6-parameter tool with low schema coverage and no output schema, the description covers the return-field shape but leaves parameter semantics (time range format, max_results/pagination, required calendar_id and reason) unaddressed. Adequate but with clear gaps.

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

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

Schema description coverage is only 17% (just the 'reason' param), leaving calendar_id, query, time_min, time_max, and max_results undocumented. The description lists returned event fields rather than explaining any parameter's format, accepted time syntax, or default behavior, so it fails to compensate for the coverage gap.

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

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

States a specific verb+resource ('List events from a calendar') and enumerates the returned fields (id, title, start_time, end_time, all_day, status), which precisely bounds the tool's scope. It does not explicitly contrast with the closest sibling calendar_get_event_details, so it stops short of a 5.

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

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

There is no statement of when to use this versus calendar_get_event_details, calendar_get_free_busy, or calendar_list_calendars. The note about what is not returned is a scope hint, not usage guidance, and 'Auto-approved' says nothing about 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 a safe read (readOnlyHint, idempotentHint, destructiveHint false), and the description adds meaningful context beyond them: the data is IT-synced cache rather than a live Workspace lookup, it can be empty, the refresh script is named, and it is auto-approved. This is exactly the extra behavioral context 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?

Four tight sentences, front-loaded with what the tool returns, then the cache caveat, then the routing to sibling tools. No sentence is filler.

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

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

With no output schema, the description compensates by enumerating returned fields, and it covers freshness/staleness, availability-check workflow, and booking workflow. An agent has everything needed to call and interpret this correctly.

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

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

Schema coverage is 100%, so both parameters including the query filter semantics are already documented in the schema. The description's list of returned fields (name, email, building, floor, capacity) describes output rather than input semantics, so it adds no parameter meaning. Baseline 3 applies.

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

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

States a specific verb and resource ('List meeting rooms and resource calendars') plus the scope ('organization's room directory'), and it is clearly distinguishable from calendar_list_calendars and calendar_list_events. An agent can identify the tool's output domain 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?

Explicitly routes to alternatives: it names calendar_get_free_busy for availability checks and calendar_create_event / calendar_update_event for booking, and it warns the list is a locally-cached snapshot that may be empty. When-to-use, when-not, and follow-up tools are all 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 non-read-only, non-idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: the mutation is field-scoped (only color changes) and requires user approval, which is not expressed in annotations.

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

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

Three compact sentences, front-loaded with the action, followed by scope, accepted values, and the approval requirement. No filler and every sentence contributes.

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 mutation scope, value domain reference, and approval gate. The main residual gap is the undocumented calendar_id/event_id semantics, which neither schema nor description clarify.

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

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

Schema coverage is 50%: color and reason are documented in the schema, while calendar_id and event_id are bare. The description restates the color id range and name example already present in the schema, adding little, and leaves the two identifier parameters unexplained.

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 ('Set a calendar event's color') and immediately scopes it against the nearest sibling behavior by clarifying that no other fields change, which separates it from calendar_update_event and calendar_set_event_visibility.

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?

Routes the agent to calendar_list_colors for valid color values and states the approval precondition, giving clear context for invocation. It does not, however, state when NOT to use it or name a competing alternative explicitly.

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

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

Annotations declare the write/safety profile (readOnlyHint=false, destructiveHint=false), and the description adds real value on top: it scopes the mutation ('Only visibility changes — no other fields are affected') and discloses a user-approval gate, which annotations do not convey. It stops short of describing failure or permission 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?

One tight paragraph, front-loaded with the action, followed by value semantics and scope limits. Every clause carries information an agent needs; nothing is padding.

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

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

For a 4-required-param mutation with no output schema, the description covers action, value semantics, scope containment, and the approval requirement. It omits what errors or confirmation look like, but the essentials for correct invocation are present.

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

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

Schema coverage is 50% and the description compensates for the most important gap by spelling out the semantics of each 'visibility' value, including that 'confidential' is a legacy synonym for 'private'. calendar_id and event_id remain undocumented, but their meaning is self-evident.

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 ('Set a calendar event's visibility') that is unambiguously distinct from calendar_get_event_visibility and calendar_update_event. 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?

Gives a clear context for invocation (changing visibility only, with a stated approval requirement) and explains what each mode means, but never routes the agent explicitly to or away from the sibling calendar_get_event_visibility or calendar_update_event.

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, destructiveHint=false, so the safety profile is known. The description adds genuinely new context: the operation is scoped to a single day on the primary calendar only, and it requires user approval. It still doesn't say what a re-call does or whether the location can be cleared.

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 scope and behavior lead, and the approval requirement is a short trailing clause. Nothing could be removed without losing meaning.

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

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

For a non-idempotent write with full annotation coverage and no output schema, the essentials (scope, target calendar, approval gate) are present. Minor gaps remain around ambiguity with the out-of-office sibling and the effect of repeating the call, but nothing blocking 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 coverage is 100% with descriptions for every parameter including the office-only qualifiers for label and building_id. The description adds no parameter syntax or constraints beyond what the schema already 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?

Specific verb ('Set') plus resource ('working-location presence'), with explicit scope: office or home, single day, primary calendar. It also names the concrete analogue ('the same picker Google Calendar's web UI exposes'), which lets an agent distinguish it from the other calendar write tools like calendar_create_out_of_office or calendar_create_event.

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

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

The description implies usage by tying it to the Google Calendar web-UI picker and notes 'Requires user approval,' which is a real precondition. However it never states when to prefer this over siblings (e.g. calendar_create_out_of_office) or when not to call it.

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

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

Annotations only say readOnly=false, idempotent=false, destructive=false; the description adds meaningful context beyond that by disclosing the approval gate and the series-splitting consequence of 'following' (earlier occurrences untouched). It still omits partial-update semantics (whether omitted fields are cleared or preserved), which matters for a 13-param mutation.

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

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

Purpose is front-loaded in the first sentence, followed by the scope semantics and the approval requirement. Every sentence carries information the agent needs and there is 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-parameter mutation with no output schema, the description covers scope and approval but omits several decision-relevant behaviors: whether this is a partial or full replace of event fields, what send_updates defaults to, and what the result of a series split looks like. Adequate but with real gaps.

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

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

Schema coverage is 46%, below the threshold where the schema can carry the load. The description compensates well for the riskiest parameter by explaining the real consequence of 'following' (series split) that the schema entry does not, and clarifies the 'this' default; remaining undocumented params (start_time, title, event_id) are largely self-explanatory.

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

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

States a specific verb and resource ('Update an existing calendar event'), which separates it from calendar_create_event and calendar_delete_event by implication. It does not explicitly distinguish itself from adjacent mutators like calendar_set_event_color or calendar_set_event_visibility, so the boundary for those overlapping edits is left to inference.

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

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

The scope enumeration effectively documents when each occurrence-mode applies, and 'Requires user approval' flags a prerequisite. However, there is no guidance on when to choose this general update over a narrower sibling such as calendar_set_event_color, nor any exclusion 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds a piece of genuinely new context — 'Auto-approved' signal that no human approval gate applies (relevant given the privacyfence approval siblings) — but says nothing about pagination, result limits, or query cost.

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

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

Two short, front-loaded sentences with no padding; the core action leads. The trailing 'Auto-approved' is curt and slightly cryptic, but nothing is wasted.

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

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

For a 3-parameter, no-output-schema search tool, the description omits what results look like and how max_results affects them. Annotations cover safety, but the return/limit behavior is left undocumented for an agent that must decide result sizing.

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

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

Schema coverage is 67%: cql has an example and reason has explanatory text, but max_results has only a default with no description. The description adds no syntax or format guidance for cql beyond naming the language, so the schema still does most of the work.

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 clear verb+resource (search Confluence) and names the query language CQL, so the agent knows this is a CQL-driven search. It does not differentiate itself from the sibling confluence_search, which likely serves a different query mode, leaving the agent to infer the distinction from the tool name alone.

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

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

There is no guidance on when to use this over confluence_search, nor any stated prerequisites. 'Auto-approved' hints at the approval workflow but is not framed as a use condition.

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-readonly, non-idempotent, non-destructive mutation. The description adds meaningful context beyond them: the body must be in HTML storage format and the operation requires user approval, which is important behavioral information for an agent.

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

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

The description is three short, front-loaded sentences with no wasted words. It immediately states the action, then adds the body format and approval prerequisite in order of importance.

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 create tool with annotations covering safety and no output schema, the description provides the key missing context: HTML storage format and the user approval requirement. It is largely complete, though it could clarify return behavior or approval failure conditions.

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

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

Schema description coverage is 60%, so the schema already documents several parameters. The description reinforces the body format and indicates that space_key refers to the target space, but it does not fully compensate for undocumented parameters like title or explain required parameters such as reason 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?

The description states a specific verb and resource: 'Create a new Confluence page in the given space.' The verb 'Create' clearly distinguishes it from sibling operations like confluence_update_page, confluence_get_page, and confluence_list_pages.

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 mentions a prerequisite ('Requires user approval') but gives no guidance on when to select this tool versus alternatives such as confluence_update_page or other creation tools. Usage is only implied by the verb 'Create'.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: local vs organization-managed install behavior, what is actually returned (file path, raw bytes, or a one-time signed-in link), and the user-approval requirement. This is exactly the behavioral depth 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?

Front-loaded with the core action, then the install-dependent branching, and every clause carries real information. It is on the verbose side, but the length is largely justified by the genuinely branching 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?

No output schema exists, and the description explicitly describes the three possible return outcomes so an agent knows what to expect. Combined with the approval and destination guidance, nothing needed to invoke 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?

With 50% schema coverage, the description compensates: it explains destination_dir's required-with-no-default semantics and the consequence of the choice, and clarifies that attachment_name comes from list_attachments. page_id and reason are undocumented here but self-evident or covered by the schema.

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

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

States a specific verb (Download) and resource (a Confluence page attachment's content), and it names the sibling confluence_list_attachments as the source of the attachment name. An agent can distinguish it from drive_download_file and gmail_download_attachment without opening any schema.

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

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

Gives clear context: obtain the attachment_name from confluence_list_attachments before calling, and choose destination_dir deliberately depending on whether the file is a user deliverable or scratch. It lacks an explicit when-not / alternative (e.g. when to prefer a page-read instead), so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds genuinely new context beyond them: the return is HTML storage format and the call 'Requires user approval', which is an important operational constraint not captured in annotations.

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

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

Three tight sentences with zero waste; the core action is front-loaded and the return format plus approval requirement follow logically. 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 covers the return value (HTML storage format) and the approval requirement. The main gap is the lack of any routing guidance against the numerous sibling retrieval tools.

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

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

Schema coverage is 50%: the 'reason' parameter is documented in the schema, but 'page_id' has no schema description. The description only implies page_id's meaning ('by page ID') without adding format or source details, so coverage of the undocumented parameter remains thin. 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 ('Fetch') and resource ('full content of a Confluence page') scoped by page ID, and discloses the return format. It does not explicitly differentiate from the close sibling confluence_get_page_by_title, but the 'by page ID' qualifier implicitly distinguishes it.

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

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

No when-to-use or when-not-to-use guidance. It does not tell the agent when to prefer this over confluence_get_page_by_title, confluence_search, or confluence_cql_search, leaving routing to inference from the tool name alone.

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

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

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive), and the description adds a genuinely new behavioral trait: 'Requires user approval.' That approval requirement materially affects how an agent should invoke the tool and is not present in the structured data.

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

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

Two short sentences, front-loaded with the lookup action and keys, followed immediately by the approval constraint. Zero 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?

For a simple read tool with no output schema and annotations covering safety, the description is largely sufficient. However, it is silent on what happens when the title is not exact or multiple pages match, and parameter coverage is thin, leaving minor gaps.

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

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

Schema coverage is only 33% (only 'reason' is documented), so the schema does not carry the burden. The description compensates partially by tying space_key and title to their meaning and stressing 'exact title,' but it gives no format guidance (space key syntax, partial-match behavior).

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 (Fetch), resource (Confluence page), and the lookup keys (space key and exact title), which distinguishes it from confluence_get_page (ID-based) and the search variants without opening a schema. It stops short of explicitly naming those siblings, so it is clear but not fully differentiated.

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 'by space key and exact title' implies when this lookup is appropriate, but there is no explicit when-to-use/when-not guidance and no mention of confluence_get_page or confluence_search as alternatives. 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 cover readOnly/idempotent/non-destructive, and the description adds meaningful context beyond them: the call is auto-approved and returns metadata only, never attachment content. It doesn't discuss pagination or handling of pages with many attachments, so not a 5.

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

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

Three short sentences, front-loaded with what is returned, then the safety/metadata note, then the alternative tool. 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?

A simple read-only list tool with annotations covering the safety profile and no output schema to explain; the description states what fields come back and which tool to use instead. 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 coverage is only 50% (page_id has no schema description) and the description only implies that page_id is a Confluence page rather than specifying its format (numeric ID vs. key). It adds marginal meaning over 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?

Specific verb (list) + resource (attachments) + scope (for a Confluence page) + the exact fields returned (names, media types, sizes). It is immediately distinguishable from the sibling confluence_download_attachment.

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

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

Explicitly routes the agent to confluence_download_attachment when actual file content is needed, which is the key alternative in this cluster. No explicit exclusions or prerequisites are stated (e.g., permissions to view the page), so it falls just short of 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds "Auto-approved," which is mildly useful given the surrounding privacyfence/approval tooling, but says nothing about pagination, result caps, or ordering 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?

Very short and front-loaded: the core purpose leads, with the field list and approval note as trailing fragments. No padding, though the terse fragments do little work.

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

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

With no output schema and only 33% parameter coverage, the description should carry more of the burden. It omits anything about pagination, the max_results cap behavior, or how to obtain a valid space_key, leaving real gaps for a listing tool.

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

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

Schema description coverage is only 33%: 'reason' is documented in the schema, but 'space_key' and 'max_results' carry no description anywhere. The description mentions returned fields rather than parameter meaning and does not explain the expected space_key format or how max_results interacts with result ordering/pagination.

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

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

Names a specific verb and resource ("List pages in a Confluence space") and even enumerates the returned fields (title, id, version). It is clear on its own, but it does not distinguish itself from siblings like confluence_search, confluence_cql_search, or confluence_get_page_by_title, which an agent must disambiguate.

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 or when-not-to-use guidance and no named alternative. The only contextual hint is "Auto-approved," which does not tell the agent when this list tool beats the search or CQL siblings.

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 the description adds two genuinely new traits: the access-scoping ('spaces the user has access to') and 'Auto-approved', which tells the agent the call will not block on human approval. It still omits pagination behavior tied to max_results.

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

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

Two short sentences, zero waste, with the scoping constraint and returned fields front-loaded. Nothing extraneous.

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 no output schema, explicitly enumerating the returned fields (key, name, type, description) is valuable. It is nearly complete, lacking only expected pagination/truncation behavior for max_results.

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

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

Schema coverage is 67%; space_type and reason are documented in the schema, while max_results has no description. The description adds no parameter-level syntax or format detail beyond the schema, so it sits at the baseline for this coverage level.

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

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

It names a specific verb and resource (list Confluence spaces) with a clear scope qualifier ('the user has access to') and enumerates the returned fields. It is distinguishable from confluence_search and confluence_list_pages by resource, though it never explicitly contrasts with them.

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

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

No when-to-use guidance or alternatives are given. An agent must infer that this is for browsing spaces rather than finding pages, and nothing tells it when to prefer confluence_search or confluence_cql_search instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. 'Auto-approved' adds a governance fact beyond the annotations, which is genuine value, but the description says nothing about result limits, pagination, or scope restrictions.

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 purpose and return value front-loaded and little waste. 'Auto-approved' is terse to the point of ambiguity about who or what approves, 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?

For a simple read-only search with no output schema, stating that excerpts are returned is adequate, but the tool omits result-count/pagination behavior tied to max_results and gives no distinction from the CQL search sibling, leaving gaps for correct invocation.

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

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

Schema coverage is 67%: query and reason are documented in the schema, while max_results (default 20) is undocumented in both schema and description. The description adds no parameter-level meaning beyond the schema, 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?

States a specific verb+resource ('Full-text search across Confluence content') and names what it returns (pages/blog posts with excerpts). However, it does not distinguish itself from the sibling confluence_cql_search, which an agent needs to choose between, 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?

No when-to-use guidance, no conditions, and no mention of alternatives such as confluence_cql_search or confluence_list_pages. 'Auto-approved' describes governance behavior, not usage context.

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 declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false; the description adds two behavioral facts beyond those: the body format (HTML storage format) and the requirement for user approval. It does not explain what approval entails or whether page versions are preserved, but it adds meaningful context.

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

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

Three short, front-loaded sentences with no filler. The most important facts — what it does, the body format, and the approval requirement — are all stated directly.

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 and annotations covering the safety profile, the description is minimally adequate. However, it leaves gaps about how page_id is obtained, whether updates overwrite content, and the mismatch between 'and/or' and the schema's required title/body.

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

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

Schema description coverage is only 50% (page_id and title have no schema descriptions). The description only restates the body format (already in schema) and incorrectly says 'title and/or body' is updatable, while the schema marks both title and body as required. It provides no help for page_id or reason.

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

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

The description clearly states the action (update) and resource (title and/or body of an existing Confluence page). The word 'existing' implicitly distinguishes it from confluence_create_page, but no sibling is explicitly named or contrasted.

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 'update ... existing Confluence page', which suggests this tool is not for creating new pages. However, it gives no explicit when-to-use guidance, alternatives, or exclusions beyond the approval requirement.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds genuinely new behavioral context: the label is created on demand as a side effect, and an approval step is required before the write. It stops short of describing failure modes or permission scope, but it clearly exceeds 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 dense sentences, front-loaded with the action and its upsert behavior, followed by the approval prerequisite. 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 small mutation tool with annotations carrying the safety profile and no output schema, the description covers the key surprises (implicit label creation, approval gate). It could add parameter format detail, but nothing critical for 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 only 33% – only 'reason' is documented in the schema. The description names the two concepts ('contact', 'label') but gives no format for resource_name (contact ID? email? resource path?) or label_name, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Add a label to a contact') and adds the upsert nuance ('creating the label if it doesn't already exist'). An agent can immediately distinguish this from the inverse sibling contacts_remove_label.

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 prerequisite 'Requires user approval' is stated, which is useful operational context. However, there is no explicit guidance on when to prefer this over contacts_update (which may also set labels) or on how the label should be identified, leaving usage 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 establish write semantics (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds non-obvious behavior: an approval gate before execution and that deletion is unavailable. It omits what happens on duplicate display_name and whether the response carries the new contact's ID, which keeps 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?

Three short sentences, front-loaded with the core action, then precondition, then format hint. Nothing is padded, though the format example is embedded mid-sentence rather than separated, making it slightly harder to scan.

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

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

For a 7-parameter mutation tool with no output schema, the description covers the risky parts: approval requirement, non-destructive nature, and the JSON encoding of the two list-like fields. It lacks any note on duplicate handling or on the 'reason' argument, leaving small gaps but nothing that would cause a failed call.

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

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

With only 43% schema description coverage, the description compensates by clarifying the two trickiest fields, emails and phones, as strings and giving a literal example '[{"value": "a@b.com", "type": "work"}]'. The remaining fields (notes, job_title, organization, display_name) are self-evident, but the required 'reason' parameter gets no mention here.

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

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

States a specific verb and resource ('Create a new contact in the user's Google address book'), which is unambiguous and clearly distinct from contacts_update, contacts_list, and contacts_search. It does not explicitly name a sibling alternative, but no other create-contact tool exists, so the risk of confusion is low.

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 adds one real precondition ('Requires user approval') and one scope exclusion ('Contact deletion is not supported'), which help an agent decide whether the tool applies. However, it never says when to prefer this over contacts_update or how to handle an existing contact, so usage guidance is only implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral detail beyond that: the call fails on a source/resource mismatch, and 'Auto-approved' discloses the approval flow. Return-shape details are absent, but no output schema exists.

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

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

Three tight sentences, front-loaded with the core action, with no repetition of the schema's enum list or 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 single-resource read with two required params and no output schema, the description covers the identifier format, the source assertion behavior, and the approval mode. The only real omission is routing guidance against contacts_search.

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

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

Schema coverage is 67% and the schema only lists the enum values for 'source'. The description goes further, explaining that 'source' asserts the expected contact kind and causes failure on mismatch, plus it documents the resource_name format by example. 'reason' is left to its self-explanatory schema text.

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 ('Fetch a single contact by resource name') and includes the canonical identifier format 'people/c12345'. This clearly distinguishes it from the sibling contacts_list and contacts_search tools.

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

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

The description implies usage (fetch one contact when you already have its resource name) but never explicitly names contacts_search or contacts_list as the alternative for lookup-by-attribute. No when-not-to-use guidance is given beyond the source assertion semantics.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: the default blending of personal and directory contacts, the meaning of the 'source' return field, and the 'Auto-approved' behavior. It stops short of describing pagination or rate limits, so a 4 is appropriate rather than 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?

The description is three tightly focused sentences: purpose first, then the source-blending behavior, then the return fields. Every sentence contributes useful information and nothing is redundant. It is concise but not maximally terse, so a 4 is warranted.

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, but the description lists the returned fields (display name, emails, phones, organization, job title, source), which compensates well for that absence. Annotations cover the read-only safety profile, and the source behavior is explained. The main omission is any detail about max_results or pagination, which keeps it from a 5.

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

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

Schema description coverage is 67%, with 'reason' and 'source' documented but 'max_results' lacking any description in either schema or tool text. The description does add meaningful rationale for the 'source' parameter by explaining the Google blending behavior, but it does not compensate for the missing 'max_results' semantics. This fits the baseline 3 for middling schema coverage.

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

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

The description states a specific verb and resource: 'List contacts from the user's Google address book.' It also clarifies the default blended scope and the source field, which makes the tool's purpose concrete. However, it does not explicitly differentiate itself from the sibling contacts_search tool, so it does not reach the sibling-differentiation standard 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 guidance for the 'source' parameter ('use source to split them apart'), which implies when to filter by personal vs directory. But it never states when to use this listing tool versus alternatives like contacts_search or contacts_get, nor does it name any alternative. Usage is therefore only implied, matching a 3.

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 supply the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description need not restate them. It does add one genuinely useful behavioral fact beyond annotations: the call is gated on user approval. However, it says nothing about whether the removal is reversible, what happens if the label is absent, or what the response contains.

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

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

Two short, front-loaded sentences with zero filler. The action is stated first and the constraint second.

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 and two undocumented required parameters, the description is thin: an agent knows what to do and that approval is needed, but not how to properly populate resource_name/label_name or what the outcome of the call is.

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

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

Schema coverage is only 33%: reason is described in the schema, but resource_name and label_name carry no description anywhere. The description provides no meaning for these two required parameters, so it fails to compensate for the coverage gap in a 3-parameter tool.

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 ("Remove a label from a contact"), which is immediately distinguishable from contacts_add_label and contacts_update among the siblings. It stops short of explicitly naming the inverse tool for differentiation, but the purpose is unambiguous.

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

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

There is no guidance on when to use this tool versus contacts_update (which may also alter labels) or contacts_add_label. The only contextual cue is "Requires user approval," which is a precondition, not usage routing.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond them: the permission constraint on directory search, the fact that no full-company search exists, and the 'Auto-approved' status. It omits pagination/return-format details, which is minor for a read tool.

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

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

Three sentences, front-loaded with the core action before the source semantics and the caveat. Every sentence carries information; 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 search with no output schema, the description supplies the essential scope rules and the directory-search limitation. The remaining gap (max_results behavior) is minor and not critical to 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 coverage is 50%, so the description must carry weight. It clarifies what 'source' does and its default beyond the schema's bare enum list, but adds nothing for 'query' or 'max_results', leaving those undocumented in both places.

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 ('Search contacts by name or email address'), which clearly separates it from the sibling contacts_list (enumerate) and contacts_get (retrieve one). It does not explicitly name those siblings, so differentiation is implied rather than stated.

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

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

Explains how to use 'source' to scope results and flags a key limitation ('directory' only finds profiles you already have contact history with). This tells the agent when directory search will and won't work, though it doesn't contrast against contacts_list.

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

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

Annotations declare non-read-only, non-idempotent, non-destructive, so the description adds value by disclosing the approval requirement and partial-update semantics. It does not detail auth scope, error behavior, or full side effects.

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

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

Four short sentences, front-loaded with purpose, then usage, approval, and formatting. 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?

Covers purpose, partial update, approval, and complex param format, but omits required resource_name/reason semantics and most mutable fields for an 8-param mutation with no output schema. Adequate but incomplete.

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

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

Schema coverage is low at 38%, so description must compensate, but it only explains emails/phones JSON formatting (with example) and leaves resource_name, reason, notes, job_title, display_name, and organization undocumented. This is partial compensation, not enough for 8 params.

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

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

States a specific verb+resource: update a contact's fields. Clear against siblings like contacts_create/get/list, though it does not explicitly differentiate or name alternatives.

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

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

Gives partial-update instruction ('Provide only the fields you want to change') and a prerequisite ('Requires user approval'). No when-to-use vs alternatives or exclusions, so usage is implied rather than fully guided.

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, destructiveHint=false, so the agent knows this is a non-idempotent write. The description usefully adds that user approval is required, a behavioral constraint absent from the annotations, but says nothing about failure modes, duplicates, or post-write state.

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, action stated first and the precondition second. 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 3-required-param write tool with no output schema, the definition covers the essential action and the approval gate, which is the key operational fact. It is thin on parameter detail and return behavior, but the gaps are modest given the self-explanatory parameter names.

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

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

Schema coverage is only 33%: only 'reason' is documented, while 'comment' and 'file_id' are bare. The description adds no parameter meaning at all, so it fails to compensate for the coverage gap, leaving format expectations unclear.

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 (add) and resource (comment on a Drive file), which is unambiguous. It does not differentiate itself from adjacent write tools like drive_write_file_content, but the action is distinct enough that no confusion arises.

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?

"Requires user approval" signals a precondition for invoking it, which is real usage guidance. However, there is no explicit when-to-use vs when-not, and no mention of alternatives for other comment-like targets (e.g. jira_add_comment).

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

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

Annotations already declare it is a non-readOnly, non-idempotent, non-destructive mutation, so the safety profile is covered by structured data. 'Auto-approved' adds useful context about the privacy-fence approval flow, but the description never says whether repeated calls create duplicates or what the mutation returns.

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

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

Two short sentences, front-loaded with the action, and no filler. Every word 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 non-idempotent creation tool with no output schema and 75% of parameters undocumented, the description is inadequate. An agent cannot tell what identifier the new file returns or how to place the file without guessing.

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

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

Schema coverage is only 25% and three parameters (name, mime_type, parent_folder_id) are undocumented in both schema and description. The description adds nothing about expected formats or defaults, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Create a new blank Drive file'), and the word 'blank' usefully distinguishes it from drive_upload_file and drive_write_file_content in the sibling set. It stops short of explicitly naming which alternative to prefer, but the scope is unambiguous.

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

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

There is no guidance on when to use this versus drive_upload_file, drive_write_file_content, or drive_sheets_create. 'Auto-approved' hints at the approval workflow but never states the conditions that make this the right 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?

Adds context beyond the annotations: the change is scoped to a single match so the rest of the document is untouched, and it requires user approval. Annotations already declare non-readOnly/non-destructive/non-idempotent, which is consistent. It does not however state error behavior when find_text matches zero or multiple locations, which matters for a non-idempotent mutator.

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?

Dense but nearly every clause earns its place, front-loading the core action and scope before the find_text caveats. The nested parenthetical about drive_get_file_content is somewhat run-on but conveys a real trap.

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 non-idempotent mutation with no output schema and 5 params, it covers the critical ambiguity (find_text matching) and the approval requirement. Remaining gaps are error/return behavior on zero or ambiguous matches, which a complete definition would ideally mention.

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

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

With 60% schema coverage, the description usefully compensates: it clarifies find_text semantics (exact plain-text, no Markdown markers, must be unique) and defines replace_all=true's effect that the schema leaves undocumented. It adds the syntax scope for replace_markdown. The 'reason' parameter is 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?

States a specific verb and resource: replace one occurrence of existing text in a Google Doc with new Markdown. It explicitly delineates scope ('without touching the rest of the document') and names the sibling tools it differs from (drive_get_file_content, drive_write_doc_content), so an agent can distinguish it from the other drive_docs_* and drive_write_doc_content tools.

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: find_text must uniquely match, include enough surrounding context, and set replace_all=true to replace every occurrence. It also warns about a pitfall relative to drive_get_file_content's Markdown-rendered output. It stops short of stating when NOT to use this tool (e.g., for wholesale rewrites vs drive_write_doc_content).

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive. The description adds real behavioral context beyond them: the opt-in semantics where each default means 'leave unchanged', and the fact that a call requires user approval. This is exactly the kind of mutation/approval detail annotations cannot express.

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 action, then the scoping/opt-in caveat, then the approval requirement. Efficient, though the opt-in explanation is slightly verbose by restating the same 'leave unchanged' idea twice.

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 mutation tool with no output schema, the description covers purpose, scoping, the critical opt-in default behavior, and the approval requirement. It leaves replace_all semantics and what the return/result looks like unstated, but overall the agent has enough to invoke 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 coverage is 75% and the schema already labels each color/boolean param as 'omit to leave unchanged'. The description generalizes this into an interaction rule – setting only highlight_color never touches bold/italic on the matched text – which is semantic value not present in the per-parameter schema text.

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

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

Names a specific verb and resource ('Apply formatting ... to existing text in a Google Doc') and explicitly scopes it against the sibling drive_docs_edit_content by noting the text itself is not changed. An agent can distinguish it from drive_docs_edit_content and drive_write_doc_content 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?

States the locating mechanism by reference ('located the same way as drive_docs_edit_content') and flags the approval prerequisite, giving clear context for use. It stops short of an explicit when-not boundary (e.g. use edit_content when you also need to replace text), but the contrast with 'without changing the text' effectively implies it.

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

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

Annotations cover only the safety profile (readOnly/idempotent/non-destructive); the description adds substantial context they don't: user approval is required, organization-managed installs ignore destination_dir, small files return inline bytes while large files return a one-time link, and Workspace docs are converted. This is exactly the beyond-annotations value the dimension rewards.

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

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

Front-loaded with the core action, then the two install-mode branches laid out in sequence. It is long, and the destination_dir guidance is repeated almost verbatim in the schema, so some trimming is possible, but every sentence carries information.

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

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

With no output schema, the description shoulders the return-value burden and does so: saved path, inline bytes, or one-time link depending on install mode. Combined with approval and export disclosure, an agent has everything needed to call it correctly.

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

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

Schema coverage is 67% and the two parameters that matter are described in the schema itself; the description's destination_dir guidance largely paraphrases the schema text. The required `reason` parameter is never mentioned in the prose. Baseline 3 is appropriate when the schema already carries the parameter detail.

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

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

States a specific verb+resource (download a Drive file) and immediately qualifies it with the export behavior for Workspace docs (text/CSV), which is behavior an agent would not guess. An agent can distinguish this from the read-oriented siblings without opening a schema.

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

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

Gives explicit contextual guidance: pick ~/Downloads when the file is a user deliverable, a scratch directory when it's only for the agent to read. It does not, however, position this against the obvious alternative drive_get_file_content, leaving that selection 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 establish readOnly/idempotent/non-destructive, but the description adds substantive behavior beyond them: it requires user approval, marks output with 'truncated': true when cut to fit, notes a scanned PDF yields no text, and flags that exact highlight/text color is returned separately in 'highlights'/'text_colors'. This is unusually rich disclosure for a read tool.

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

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

The Markdown syntax enumeration is long, but it is front-loaded after the core purpose and every clause carries format/round-trip information an agent needs. It is dense rather than padded, though the inline example markup could be trimmed.

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 complex multi-format reader with no output schema and only 2 params, the description fully covers what is returned per file type, truncation, edge cases (scanned PDFs, images), and the approval requirement. Nothing essential to calling 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?

With 50% schema coverage, the baseline is 3. The description clarifies that file_id identifies the Drive file and that 'reason' is the approval justification implicitly, but it adds no syntax for file_id beyond 'by id'; the schema already documents the 'reason' parameter's one-sentence format.

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 ('Fetch the content of a Drive file by id') and immediately differentiates itself by output format per file type (Doc→Markdown, Sheet→CSV, Slides→text, PDF/docx→extracted text, zip→entries). An agent can distinguish it from the many sibling drive_* tools without opening a schema.

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

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

Explicitly routes the agent elsewhere when appropriate: 'Other files, such as images, only get a placeholder: use drive_download_file for those.' It also names the round-trip targets (drive_write_doc_content, drive_docs_edit_content) so the agent understands this is the read counterpart to those write tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds a non-annotation behavioral fact — 'Auto-approved' — which matters in a catalog containing privacyfence_await_approval, telling the agent no gate will block this call. It does not describe error behavior for a bad id, 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?

One front-loaded sentence naming the operation, key, and returned fields, followed by a short 'Auto-approved.' fragment that carries real approval-flow information. Efficient overall, though the trailing fragment is slightly abrupt rather than fully integrated.

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 tool with rich annotations and no output schema, the description is nearly sufficient: it enumerates the main metadata fields so the agent knows what comes back, and flags auto-approval. Missing only edge-case behavior (invalid id, permissions on shared files).

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

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

Schema coverage is only 50%: 'reason' is documented in the schema, 'file_id' is not. The description partially compensates by specifying 'by id', clarifying what file_id means and that it targets one file, but adds no format or example beyond that. Baseline 3 for a low-coverage two-param schema.

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

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

States a specific verb (Fetch), resource (metadata for a single Drive file), lookup key (by id), and enumerates what the metadata includes (name, owners, times, sharing status). It is clearly distinguishable from drive_list_files (plural, filtered listing) and drive_get_file_content (content, not metadata).

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 'single file by id' framing implies you must already have the file id, and 'Auto-approved' hints no approval round-trip is needed, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. drive_list_files for discovery). 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the returned field list and the 'Auto-approved' note, but that note is ambiguous (approval-free execution? pre-vetted call?) and no pagination or result-limit behavior is disclosed.

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

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

Two short sentences with the action and the return payload front-loaded; no filler. 'Auto-approved' is terse but its meaning is murky, slightly weakening an otherwise efficient structure.

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, enumerating the returned fields is valuable and correctly done. But for a search tool it omits result-limit/pagination behavior, the meaning of the required 'reason' field, and any routing to sibling Drive tools, leaving clear gaps.

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

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

Schema coverage is 67%; the query parameter is well documented in the schema itself (Drive 'q' syntax with examples and a doc link), so the description need not repeat it. However max_results has no description anywhere, and the description adds nothing about parameter semantics, so it sits at the baseline.

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

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

States a specific verb ('Search') and resource ('Google Drive files') and even enumerates the returned metadata fields (id, name, mime_type, owners, sharing status). It is distinguishable from drive_get_file_metadata and drive_list_folder by the 'search' framing, though it never explicitly contrasts itself with 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 description gives no when-to-use guidance, no prerequisites, and no pointer to alternatives such as drive_list_folder for browsing a known folder or drive_get_file_metadata for a known id. The agent must infer the selection from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds two genuinely useful behavioral facts — that it returns only direct children (not recursive) and that it is auto-approved — but says nothing about pagination, result ordering, or how max_results interacts with the returned set.

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

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

Two tight, front-loaded sentences with no filler; the core behavior leads. 'Auto-approved' is terse to the point of being cryptic, but nothing here 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 3-parameter, no-output-schema read tool, the description gives the essential scope but omits pagination behavior and result format, which an agent needs to call it correctly when a folder has many children. Adequate but with clear gaps.

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

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

Schema coverage is only 33%: folder_id and max_results have no descriptions at all. The description says the folder is identified 'by id' and clarifies the output is direct children, but leaves max_results (default 50) and the expected id format entirely unexplained, so it does not compensate for the coverage gap.

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

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

States a specific verb (List), resource (Drive folder children), scope (direct children, by id). An agent can tell it apart from drive_list_shared_drives, but the distinction from the very similar drive_list_files is not addressed, which is the sibling it most overlaps 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?

There is no when-to-use guidance and no comparison to drive_list_files or drive_get_file_metadata, which are the natural alternatives for navigating Drive. 'Auto-approved' gestures at approval flow 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful 'Auto-approved' detail (no human approval gate) and states the return shape (id and name), but says nothing about pagination or how max_results caps the result set.

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

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

A single tight sentence with the resource front-loaded and the return shape in parentheses. 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 helpfully names the returned fields, and 'Auto-approved' clarifies the approval flow. However, it omits pagination/limit semantics for max_results, leaving an agent unclear on how to page or bound results.

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

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

Schema description coverage is only 50%: 'reason' is documented but 'max_results' has no description in the schema. The tool description mentions neither parameter, so it does not compensate for the gap or clarify default/limit behavior.

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 (Google Workspace Shared Drives) with a scope qualifier ('the user can access'), which clearly separates it from drive_list_files. It does not explicitly name a sibling tool, but the resource is unambiguous.

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

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

There is no guidance on when to use this versus drive_list_files or other drive listing tools. 'Auto-approved' hints at the approval workflow 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, and the description adds a genuinely useful trait not in the structured data: the call requires user approval. It still omits what happens to sharing/permissions after the move and why the operation is not idempotent, 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 short, front-loaded sentences with no waste; the core action leads and the approval constraint follows. Nothing is padded or redundant.

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

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

For a 3-parameter mutation with no output schema and only one documented parameter, the description covers the action and the approval gate but leaves the parameter formats and post-move side effects unspecified. Adequate but with visible gaps.

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

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

Schema description coverage is only 33% (only 'reason' is documented), so the description must compensate. 'Move a Drive file to a different folder' implicitly maps file_id to the source and destination_folder_id to the target, but adds no format detail (ID vs. name, shared-drive restrictions), leaving half the compensation undone.

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 ('Move a Drive file to a different folder'), so the agent knows exactly what the tool does. It does not, however, differentiate itself from the many other drive_* siblings or clarify that this is the only move/parent-change operation.

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 or when-not-to-use guidance and no alternatives named, even though the sibling list is packed with drive tools (drive_list_folder, drive_get_file_metadata). 'Requires user approval' is an operational precondition, not usage guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the write/non-destructive profile is covered. The description adds genuinely useful context by disclosing the user-approval requirement, but says nothing about duplicate-title behavior or mutation side effects beyond that.

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

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

Two short, front-loaded sentences with no filler; the core action leads and the approval constraint follows. Efficient, though the brevity contributes to the documentation gaps noted elsewhere.

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 and only 20% parameter coverage, the description should explain the required title/spreadsheet_id semantics and any uniqueness constraints. Only the approval requirement is covered, leaving most agent-relevant detail 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 only 20% – just 'reason' is documented. spreadsheet_id, title, rows and cols carry no explanation in either schema or description, and the description adds nothing (e.g. whether title must be unique, what rows/cols defaults mean). The required-vs-optional distinction is left entirely 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?

States a specific verb and resource ('add a new tab to an existing spreadsheet'), which clearly distinguishes it from drive_sheets_create (new spreadsheet) and drive_sheets_rename_sheet. It does not explicitly name those siblings, but the action is unambiguous.

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

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

The only usage signal is 'Requires user approval', which is a prerequisite rather than guidance. It never says when to add a sheet versus renaming or creating one, nor what happens if the sheet already exists.

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 is a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. 'Auto-approved' adds genuinely useful context about the approval path, but the description omits return details, ownership/location defaults, and quota behavior for a creation tool.

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

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

Two compact sentences, no filler, with the core action front-loaded. 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?

No output schema, so the description needn't explain return values, but for a creation tool it should indicate where the new spreadsheet is created by default and how the required reason parameter fits in. The approval note helps but the picture is incomplete.

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

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

Schema coverage is 50%: sheet_titles and parent_folder_id are documented in the schema, while name and the required reason are not. The description adds the concept of 'named tabs' (mapping to sheet_titles) but says nothing about where the file lands or what 'reason' is for. Partial compensation only.

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: create a Google Sheets spreadsheet, with the optional tab-titling capability named. It is clear enough to separate from sibling reads/writes like drive_sheets_write_range or drive_create_blank_file, though it doesn't explicitly contrast with the generic blank-file creator.

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

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

The description gives no when-to-use guidance or alternatives, and nothing about prerequisites such as folder placement or required Drive scopes. 'Auto-approved' hints at an approval flow but does not tell the agent when this tool is the right choice versus drive_create_blank_file.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it states the deleted content is not recoverable through PrivacyFence, that remaining rows/columns shift to close the gap, and that user approval is required. These are exactly the behavioral facts an agent needs before invoking a destructive mutation.

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

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

Three sentences, all front-loaded: what is deleted, that it is irreversible, and the side effect on remaining rows. Zero filler and no 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 destructive mutation with no output schema, the description covers the critical unknowns (irreversibility, gap-closing shift, approval gate). It omits any note on what the call returns or what happens on out-of-range indices, which is a minor residual gap.

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

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

Schema coverage is 67% and the description adds no parameter-level meaning — it never explains that start_index is 0-based inclusive, how count interacts with the range, or what dimension accepts. With most params documented in the schema, 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 (delete) and resource (rows or columns from a sheet tab), with the scope of what is removed ('including any values, formulas, and formatting'). An agent can distinguish this from drive_sheets_insert_dimensions 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?

The description conveys that this is a destructive operation requiring user approval, which implies caution before use, but it never names the alternative (insert_dimensions) or states the condition that should select delete over other sheet-editing tools. Usage is implied rather than guided.

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, so the mutation/safety profile is known. The description adds genuine context beyond that: partial-update semantics (unset parameters never touch unrelated existing formatting) and an approval requirement. It stops short of describing merge/unmerge reversibility or how the required 'reason' approval flow works.

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 purpose, then the crucial opt-in semantics, then the approval constraint. No filler; every sentence carries information an agent needs for 16 parameters.

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 16-parameter mutation tool with no output schema, the description covers purpose, the non-obvious opt-in default behavior, and the approval gate, which is close to sufficient. Minor gaps remain around merge/unmerge specifics and how freeze settings interact with the target range.

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 94%, so almost every parameter is already documented in the schema (including the 'omit to leave unchanged' note per field). The description's list of formatting facets is a helpful overview but adds no syntax or value-range detail beyond what the schema already 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 (apply formatting) and resource (range in a spreadsheet), then enumerates exactly which formatting aspects are covered — bold/italic, colors, number format, alignment, wrap, width, freeze, merge. This distinguishes it clearly from siblings like drive_sheets_write_range (values) and drive_docs_format_content (docs).

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 real guidance on how to call it (each parameter is opt-in; defaults leave the aspect unchanged), which is useful context for invocation. However, it never states when to choose this tool over alternatives such as drive_sheets_write_range or drive_sheets_get_metadata, so tool-selection guidance is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds 'Auto-approved,' which is useful approval context beyond annotations, but it does not disclose access requirements, rate limits, or what happens if the spreadsheet is inaccessible.

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

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

Two short sentences, front-loaded with the core action and return fields; 'Auto-approved' is brief and earns its place as approval context. It is slightly cryptic but has little waste.

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

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

For a simple read-only metadata tool whose annotations cover safety, the description states the returned fields, but it omits usage guidance, the required reason parameter's role, and any access constraints. Adequate but with clear gaps.

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

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

Schema description coverage is 50%: reason is documented, spreadsheet_id is not. The description adds no syntax, format, or meaning beyond 'in a spreadsheet,' so it does not compensate for the underexplained 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?

Lists the tabs in a spreadsheet and names the returned fields (id, title, index, row/column count), which is a specific verb+resource. It does not explicitly contrast with sibling read tools like drive_sheets_get_values or drive_get_file_metadata, so it falls short of 5.

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

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

No when-to-use guidance or alternatives are given. 'Auto-approved' is an approval attribute, not usage direction, and the description never says when to choose this over drive_sheets_get_values or drive_get_file_metadata.

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, lowering the bar. The description nonetheless adds a meaningful behavioral fact not in the annotations — 'Requires user approval' — plus the effect of include_formatting on the returned payload, which is real value.

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

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

One dense sentence that front-loads the core action and the render-mode variation; nothing is wasted, though the nested 'display values... or formulas... and optionally formatting' phrasing is slightly heavy.

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, but the description communicates what comes back (display values, underlying values, formulas, optional formatting) and flags the approval requirement. Combined with annotations that carry the safety profile, an agent has enough to call it correctly.

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

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

Schema description coverage is 80%, so the schema already documents spreadsheet_id, range_a1, reason, include_formatting and value_render_option in detail. The description largely restates the render options without adding syntax or constraints 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?

States a specific verb and resource ('read a range of cells from a spreadsheet') and enumerates the three render modes plus optional formatting, so an agent knows exactly what the tool returns. It does not explicitly differentiate itself from siblings like drive_sheets_get_metadata or drive_sheets_write_range, which caps it below a 5.

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

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

Usage is implied through the value_render_option guidance ('use this to read formulas') and the note that approval is required, but there is no explicit when-to-use-this-vs-alternatives statement relative to drive_sheets_get_metadata or the write 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 the mutation/safety profile (readOnlyHint=false, destructiveHint=false), and the description usefully adds that values and formulas are untouched while formulas referencing shifted cells are auto-adjusted, plus a user-approval requirement. These are non-obvious behavioral facts beyond the annotations, though the adjustment/approval mechanics are not detailed further.

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: core action first, then behavioral consequences, then the approval constraint. Each sentence carries information with little waste.

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

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

For a 7-parameter mutation tool with no output schema, the description covers the essential semantics (positional shift, formula adjustment, approval). Remaining parameter details live in the schema, so an agent has enough to call it correctly.

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

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

Schema coverage is 71%, so most but not all parameters are self-documented. The description's 'shifting existing content after the insertion point' loosely conveys the start_index semantics, but it adds nothing about count, dimension values, or inherit_from_before beyond what the schema already says. 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 (insert) and resource (blank rows or columns into a sheet tab) with the exact effect on existing content. An agent can immediately distinguish this from the sibling drive_sheets_delete_dimensions by the insert vs. delete action.

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 clear purpose implies the usage scenario (need blank rows/columns mid-sheet), but the description never explicitly states when to prefer this over alternatives, nor names delete_dimensions as the inverse operation or add_sheet as a different approach. Usage is inferred rather than guided.

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, so the mutation profile is covered. The description adds genuinely new context: 'Requires user approval' and the no-delete-tool workaround, which 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?

Three short sentences, front-loaded with the core action, then the workaround, then the approval requirement. No filler and each 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 four-parameter mutation with no output schema, the description supplies the approval requirement and the deletion workaround, which are the key operational facts. A note on what happens if the title already exists would complete it, but nothing essential 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 50%: 'reason' and 'sheet_id' are documented in the schema, while 'spreadsheet_id' and 'new_title' are not. The description implies the new_title semantics via 'rename' but adds no format or constraint detail, so it only marginally compensates for the gap.

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

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

States a specific verb+resource ('Rename an existing tab in a spreadsheet'), which clearly separates it from drive_sheets_add_sheet and the other sheet tools in the sibling list. The scope (existing tab) 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?

Explicitly covers the deletion workaround — 'There is no delete-sheet tool — to mark a tab for removal, rename it... and the user can delete it by hand' — which tells the agent when to reach for this tool beyond a simple rename. It doesn't enumerate exclusion conditions for ordinary renames, but the routing guidance is concrete.

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 declare the mutation profile (readOnly=false, idempotent=false, destructive=false), and the description adds real behavior beyond them: how '=' strings are evaluated as formulas and that writing empty rows/columns clears those cells. The approval requirement is also surfaced. It does not describe return values, but no output schema exists to replace that.

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

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

Four tightly scoped sentences, front-loaded with the core action and followed by the two most surprising behaviors (formula evaluation, clearing on empty) and the approval requirement. 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 non-idempotent write tool with no output schema, the description covers the salient semantics an agent needs: formula handling, overwrite/clearing effects, and approval. Remaining gaps (rate limits, error behavior) are minor and atypical to document 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 coverage is 75%, so most params are documented structurally, but the description adds meaning the schema lacks: the formula-evaluation semantics of cell strings, which is not conveyed by the values example. It doesn't mention the 'reason' parameter, a minor gap.

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

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

States a specific verb+resource: writing values/formulas into a range of an existing spreadsheet. It clearly contrasts with reading (drive_sheets_get_values) by scoping to 'existing spreadsheet', but does not explicitly name siblings such as drive_sheets_format_range or drive_write_file_content.

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 '=' formula note effectively routes agents away from hunting for a separate formula tool, and 'Requires user approval' hints at the invocation context. However, there is no explicit when-to-use guidance versus siblings like drive_sheets_format_range or drive_write_file_content.

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

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

Annotations cover the safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds context they cannot: 'Requires user approval', the fact that content_base64 is decoded by PrivacyFence itself, and that on org-managed installs local_path resolves on the server not the user's machine.

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 purpose and the sibling comparison are front-loaded, and nearly every clause carries operational information. It is nonetheless a single dense block with stacked parentheticals that could be broken into shorter statements 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 a 6-param mutation tool with no output schema and thin schema coverage, the description covers the central usage paths, approval requirement, and install-mode caveat well. It stops short of documenting parent_folder_id, so an agent has no guidance on target-location behavior.

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

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

Schema coverage is only 17% (only 'reason' is documented), so the description must carry the load — and it does for three of six params, explaining exactly-one-of semantics, that 'name' is required with content_base64, and what upload_id refers to. parent_folder_id and the full meaning of name are never mentioned, leaving a real gap.

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

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

States a specific verb and resource ('Upload any file ... to Drive as a new file') and immediately distinguishes itself from the sibling drive_write_file_content by scoping to binary vs UTF-8 text. An agent can select this over its nearest alternative 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?

Explicit routing: 'use this instead of drive_write_file_content for any binary file', plus a decision procedure for the three input modes (local_path, content_base64, upload_id) with the conditions that favor each. It even gives a fallback path when local_path errors and an org-managed-install caveat.

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?

Discloses the critical destructive side effect ('Clears the existing document content before writing') and an operational gate ('Requires user approval') that the annotations do not convey. It also specifies the exact supported Markdown grammar, which is the behavior an agent must satisfy. The only tension is destructiveHint=false, but that hint concerns deleting the resource, and here the document survives with its contents replaced, which the description states plainly rather than concealing.

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?

Long but dense: the formatting grammar is front-loaded and every clause is functional rather than filler. It is a single packed sentence followed by routing and approval notes, so it reads well even if it could be broken into shorter segments.

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