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 that isn't in them: 'Requires user approval' and the concrete return structure ({script_id, files} with {name, type, source} and enum values). That is real behavioral disclosure beyond the structured fields.

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

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

Three tight sentences, front-loaded with the action and scope, then the return shape, then routing and approval. Every clause carries information; 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?

With no output schema, the description compensates by describing the exact return object and type values, and it covers the approval requirement and sibling routing. 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 description coverage is 100%, so both parameters (script_id, reason) are already documented in the schema, including script_id's provenance. The description echoes the script_id source but adds no syntax or format detail beyond what the schema provides; 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+resource ('Fetch the full source of a Google Apps Script project') and pins the scope explicitly (every .gs/.html file plus appsscript.json manifest). It even enumerates the return shape, so an agent can distinguish it from apps_script_list_projects and apps_script_write_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?

It routes the agent on both sides: where the script_id comes from (apps_script_list_projects) and which sibling to use to modify source (apps_script_write_content). It also flags the approval prerequisite. It stops short of explicit when-not/exclusion guidance, but the context is clear.

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

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

Annotations already cover read-only safety, idempotency, and non-destructiveness. The description adds meaningful behavioral context beyond those annotations: pagination behavior via max_results, the user-approval requirement, the fact that these are user-triggered runs, and the shape/status values of the returned records.

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

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

The description is front-loaded with the core action and scope, then moves through return shape, pagination, prerequisite, and approval requirement. It is information-dense and mostly earns its length, though the single dense paragraph could be slightly easier 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?

There is no output schema, so the description appropriately explains the returned list shape, status examples, and duration format. Combined with the annotations and fully documented input schema, it gives the agent enough context to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents script_id, reason, and max_results thoroughly. The description reinforces that script_id comes from apps_script_list_projects and mentions max_results paging, but adds little semantic detail beyond the schema.

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

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

The description names a specific verb and resource: reading execution-log results for a script run outside PrivacyFence. It distinguishes the tool from a live console.log transcript and lists the exact return fields, so an agent can identify what the tool 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?

The description gives clear context for when this tool applies: recent user-triggered runs outside PrivacyFence, not a live transcript. It also tells the agent where to obtain script_id and that user approval is required. It does not name an explicit alternative tool for live-log scenarios, but it does provide the key usage conditions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that: the container-bound exclusion rule, that results come back in Drive's order, that it paginates across pages, and the operational note that the call is auto-approved.

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

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

Five tight sentences, front-loaded with scope and the exclusion rule, then return shape, pagination, and routing. Every sentence earns its place with no 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?

With no output schema, the description compensates by enumerating the returned fields {id, name, created_time, modified_time} and the ordering. Combined with the exclusions, pagination note, and sibling routing, an agent has everything needed 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?

Schema coverage is 100%, so the schema already defines both parameters. The description nonetheless adds meaning the schema lacks: that max_results is honored across pagination ('Reads up to max_results items across pages'), which clarifies the truncation behavior of the required cap.

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 standalone Google Apps Script projects') and immediately bounds the scope by excluding container-bound scripts attached to Sheets/Docs/Forms. This lets an agent distinguish it from sibling tools like apps_script_get_content and drive_list_files 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: it lists only standalone projects and explicitly routes the agent forward ('Pass an id as script_id to apps_script_get_content and the other Apps Script tools'). It does not name a competing list tool or state when-not-to-use, so it falls short of a full 5.

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

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

Goes well beyond the annotations: it discloses that omitted files are deleted, that nothing is executed by PrivacyFence, that the write requires user approval, and even the return shape {script_id, file_count}. Annotations only supply readOnlyHint=false, idempotentHint=false, destructiveHint=false; the description's explicit 'any file left out is deleted' is strictly more informative, though it sits in tension with destructiveHint=false and the description could have noted the tension explicitly.

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-loads the core action and the destructive-replacement caveat before the lower-priority details. Every sentence carries load, though the parenthetical about fetching current content and the trailing approval sentence could be tightened slightly.

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 destructive write with no output schema, the description covers what an agent needs: the replacement semantics, the pre-fetch step, the approval gate, the fact that execution is out of scope, and the returned fields. Nothing material is left for the agent to infer.

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

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

Schema description coverage is 100%, so the schema already documents script_id, files, and reason fully. The description reinforces the 'whole file set, not just changed files' semantics of `files`, but adds no syntax or format detail beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource (write new source to an Apps Script project) and immediately distinguishes itself from siblings by declaring it is a full-file-set replacement, not a partial edit. An agent can tell it apart from apps_script_get_content and drive_write_doc_content 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 states when to use it and how to use it safely: pass every file the project should have, fetch the current set with apps_script_get_content first if you aren't touching other files. It also sets expectations about the downstream step (the user runs the script themselves in the editor) and 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?

Goes well beyond the annotations: discloses the 10,000-row cap, the exact column layout and multi-value join delimiter, that the objects themselves are never returned (only a summary payload), the no-match behavior (no file, rows 0), the org-managed download_url fallback, and the approval requirement. The read/write semantics are disclosed clearly enough to reconcile with readOnlyHint/destructiveHint=false (nothing remote is mutated or destroyed).

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 front-loaded: the core action and cap come first, then output shape, then edge cases and the alternative tool. Every sentence carries a distinct fact (cap, columns, return payload, no-match, org-managed fallback, approval) with no repetition of the name or title.

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

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

With no output schema, the description carries the return contract itself ({rows, columns, sha256, path, name, size_bytes, delivery}), plus the failure/edge behavior and the org-managed variant. For an export tool with user-approval and environment-dependent delivery, nothing material is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including the .csv/.json format selection and the empty-file_name default. The description reinforces output-shape semantics (columns, multi-value join) but adds no parameter 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+resource+scope: writes every Jira Assets object matching an AQL query, capped at 10,000, to a CSV/JSON file. It also explicitly distinguishes itself from the sibling assets_search_objects for reading a few objects, so an agent can route 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?

Gives explicit when-to-use (bulk export via AQL), when-not (use assets_search_objects to read a few objects in the reply), and prerequisites (requires user approval; on org-managed installs nothing lands in destination_dir and a one-time download_url is returned instead). Also defines the zero-match case.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond annotations: the approval requirement and the exact return payload shape. It does not mention pagination or result caps, 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 action and resource, then the return shape, then the disambiguation and prerequisite. 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?

With no output schema, the description supplies the return structure inline, plus the approval prerequisite and the sibling alternative. Nothing an agent needs to invoke this read-only lookup correctly is missing.

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

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

Schema description coverage is 100%, so both object_id and reason are already documented in the schema, and the description adds no format or sourcing detail beyond 'one Jira Assets object'. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb and resource ('List the Jira tickets connected to one Jira Assets object') with an explicit cardinality scope of one object. It also names the sibling it is not ('Use assets_get_object to read the object itself'), so an agent can distinguish the two 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 explicitly routes the agent to assets_get_object when the object itself (not its connected tickets) is wanted, and flags the 'Requires user approval' prerequisite. It lacks an explicit negative case for this tool (e.g., when tickets are not the right resource), but the selection guidance is clear.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, so the bar is lower. The description adds genuinely new context: the 'Requires user approval' gate, and it enumerates the returned fields, which is valuable given 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: purpose first, then the return shape, then routing and the approval note. Every sentence earns its place with no filler.

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

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

With no output schema, the explicit return-field list is exactly what the agent needs, and the approval requirement plus sibling routing round out the picture. Nothing essential is missing for a read tool.

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

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

Schema coverage is 100% and the schema already documents object_id (with its origin) and reason. The description adds nothing about parameter syntax or format beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Read), resource (one Jira Assets object), and scope (every attribute value and its outbound references). This cleanly distinguishes it from siblings like assets_search_objects and assets_get_related_objects.

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?

Names the exact prerequisite tool (assets_search_objects to find the object id) and the follow-up alternative (assets_get_related_objects to follow links). This gives the agent explicit routing without 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 cover the read-only/idempotent/non-destructive profile, but the description goes further by disclosing the return shape ({root_id, objects, edges}), the hard caps (depth 1-3, at most 200 objects), the meaning of the truncated flag, and the user-approval requirement. These are behavioral traits an agent cannot derive from the annotations or schema.

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

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

Front-loaded with the core action, then the return contract, then the sibling routing, then the approval constraint. Every clause earns its place; the dense middle sentence is dense because it is disclosing return and limit semantics that no output schema provides.

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

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

There is no output schema, so the description compensates by describing the response fields, limits, and truncation semantics, and it adds the approval prerequisite. For a five-parameter read tool with no output schema, nothing an agent needs 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 100% and the description's parameter mentions (depth 1 to 3, at most 200 objects, direction choices) simply restate what the schema already documents per-parameter. Baseline 3 is appropriate since the schema carries the parameter documentation.

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

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

The description states a specific verb (Read) plus a precisely scoped resource (Jira Assets objects linked to one object) and the traversal semantics (references outbound, inbound or both, up to three hops). An agent can distinguish it from assets_get_object and assets_search_objects without opening any schema.

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

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

It explicitly routes the agent: 'Use assets_get_object to read only the object itself', naming an alternative and the condition that selects it. It does not, however, address the similarly named relationship-oriented sibling assets_get_connected_tickets or state a when-not-to-use condition, so context is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint/idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral context beyond that: the exact return shape, the exclusion of system attributes, and the 'Auto-approved' approval status. No pagination or rate-limit notes, which keeps it short of a 5.

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

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

Front-loads the core action, then return fields, then exclusions, then routing. Every clause carries information and none 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 the returned fields, and it names the prerequisite and follow-up tools. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so both parameters are documented in the schema, and the description's pointer to assets_list_object_types for the id largely duplicates the object_type_id schema text. The 'reason' parameter is not elaborated on at all, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the attribute definitions of one Jira Assets object type') and adds the distinguishing scope note that it includes reference attributes while excluding system attributes. An agent can distinguish this from assets_list_object_types and assets_search_objects 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 names the sibling to call first for the type id (assets_list_object_types) and the sibling for reading the objects themselves (assets_search_objects), giving a clear workflow position for this tool. Nothing about when to reach for it is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine extra context by disclosing the exact return fields and the 'Auto-approved' approval behavior, though it omits pagination or size limits.

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

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

Three tightly packed sentences: purpose first, return shape second, navigation third. Every sentence earns its place with no redundant restatement of the name.

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

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

Although there is no output schema, the description enumerates the returned fields and supplies the upstream and downstream tool context, so 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 description coverage is 100% with only two well-documented parameters, so the schema already carries the semantics. The description implies schema_id scoping but adds no format or syntax detail beyond the schema, making baseline 3 correct.

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

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

States a specific verb and resource with scope ('List the object types in one Jira Assets schema'), and even enumerates the returned shape {id, name, parent_id, description, object_count}. An agent can distinguish this from assets_list_attributes and assets_search_objects immediately.

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 names the prerequisite tool (assets_list_schemas to find the schema id) and the follow-up alternative (assets_list_attributes), giving a full navigation path. Nothing about when to use this vs siblings is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new context: the return shape (id, name, key, description, object_count, object_type_count), the max_results truncation behavior, and the 'Auto-approved' approval status.

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 front-loaded sentences with no filler: purpose and scope first, then return shape and limit, then the drill-down hint. Every sentence contributes actionable information.

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

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

There is no output schema, so the inline description of returned fields is essential and present, and the safety profile is fully covered by annotations. Nothing needed to call this read-only list tool 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 100% schema description coverage, both parameters are already fully documented in the schema, and the description only restates the max_results cap ('at most max_results entries') without adding format or edge-case meaning. Baseline 3 is correct when the schema carries the parameter semantics.

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

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

States a specific verb (List) and resource (Jira Assets object schemas) with an explicit scope (the connected Atlassian site). It also enumerates the returned fields, so an agent can distinguish it from sibling readers like assets_search_objects or assets_get_object 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 a clear next-step context by pointing to assets_list_object_types to inspect schema contents, which routes drill-down behavior. It stops short of explicitly contrasting with assets_search_objects or stating when *not* to call this, so it is clear context rather than full when/when-not 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 cover the read/idempotent/non-destructive profile, but the description adds two things they do not: a 'Requires user approval' gating requirement and the concrete shape of the returned list. With no output schema, enumerating the return fields is genuinely load-bearing 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?

Four sentences, front-loaded with purpose, then return shape, then sibling routing, then the approval caveat. The one verbose element (the field list) substitutes for a missing output schema, so it 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 3-parameter query tool with no output schema, the description covers purpose, return contents, result-size cap, alternative tools, and the approval requirement. Nothing an agent needs before calling is missing.

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

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

Schema description coverage is 100%, so aql, reason, and max_results are already fully documented in the schema; the description only echoes the max_results cap ('at most max_results entries'). It adds no syntax or format meaning beyond the structured fields.

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

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

States a specific verb (Search) and resource (Jira Assets objects) plus the mechanism (AQL query) and what is returned (objects with attribute values). This cleanly separates it from assets_get_object, assets_export_objects, and assets_list_attributes, which it names.

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 alternatives with the condition for each: assets_get_object for a single object by id, assets_export_objects when the result is large, assets_list_attributes to discover a type's attributes. This is the when-to-use-an-alternative guidance the rubric asks for.

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, so the safety profile is covered. The description adds real context beyond them: the exact return shape including conditional conference_link, the all-day limitation, and a user-approval gate. It does not disclose side effects such as invitations being emailed to attendees, which keeps it short of a 5.

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

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

Four front-loaded sentences, each earning its place: purpose, return payload, scope constraint, sibling routing, and approval requirement. No filler or restatement of the tool name.

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

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

For a 12-parameter mutation with no output schema, the description compensates by describing the return payload and the conditional conference_link, plus the creation constraint and approval gate. Combined with 100% schema coverage, 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 description coverage is 100%, including timestamp formats, RRULE syntax, default-empty semantics and cross-references to calendar_list_calendars/list_rooms/list_colors, so the baseline is 3. The description only echoes those lookup hints (rooms, colors) rather than adding new parameter semantics.

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

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

States a specific verb and resource ('Create a new calendar event') and immediately bounds the scope with 'Timed events only: all-day events cannot be created.' It differentiates itself from calendar_create_out_of_office and the room/color lookup siblings by name, so an agent can route without opening a schema.

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

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

Gives explicit alternatives with their selecting conditions: calendar_create_out_of_office for time off, calendar_list_rooms to find bookable rooms, calendar_list_colors for color ids. It also states a hard exclusion (no all-day events) and a precondition (requires user approval), leaving little 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 only declare readOnly=false, idempotent=false, destructive=false. The description goes well beyond that: it discloses the key side effect (auto-declines new conflicting invitations), scopes it precisely (existing invitations are left alone), states the output shape, and flags the approval requirement.

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 the core action, then the behavioral caveat, return shape, format constraint, alternative, and approval note. No filler; 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 mutation tool with no output schema, the description supplies the return fields, the timed-only constraint, the side-effect behavior, and the approval prerequisite — everything an agent needs to call it correctly and predict the outcome.

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

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

Schema description coverage is 100%, so every parameter is already documented with format details (RFC 3339, defaults, decline_message semantics). The description adds no additional parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb (Create), resource (out-of-office event), and scope (primary calendar). It explicitly distinguishes itself from the sibling calendar_create_event, 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?

Names the alternative (calendar_create_event for an ordinary event) and gives an explicit when-not constraint (timed events only, not all-day). The 'requires user approval' note also tells the agent a precondition exists before invocation.

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

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

Annotations already declare destructive=true, idempotent=false, readOnly=false, so the safety profile is covered. The description adds real value beyond them: precise recurring-series semantics, a stated return shape ({id, deleted, scope}) despite no output schema, and the 'Requires user approval' constraint. Minor gap: send_updates notification behavior is left entirely to the schema.

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

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

Front-loads the action, then the scope semantics, then the return shape, then the alternative, then the approval gate. Every sentence carries distinct information with no restatement of the name or schema.

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

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

With 5 parameters, no output schema, and no enums, the description supplies the missing return shape, the destructive-scope nuance, and the approval requirement. An agent has everything needed to call this correctly for both recurring and single events.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining what 'following' actually does ('ends the series just before this instance... keeping earlier ones'), which the schema only labels. It does not extend meaning for reason, calendar_id, or send_updates beyond their 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 ('Delete a calendar event') and immediately differentiates the scope modes that distinguish this tool from a generic delete. It also names the sibling calendar_update_event as the non-deletion alternative, so an agent can route correctly without opening schemas.

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

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

Explicitly routes the agent: 'Use calendar_update_event instead to change an event rather than remove it,' plus per-scope conditions describing exactly which mode to pick. It also flags the approval prerequisite, leaving no inference 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine value beyond that: the exact return field set, an explicit exclusion list (conferencing links and attachments are NOT included), and the approval requirement. Missing are any auth/scope caveats or visibility 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?

Front-loaded with purpose, then return shape, then the alternative, then the gating requirement. Efficient, though the return-field enumeration is dense and reads as prose where a compact list would be more scannable.

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

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

With no output schema, the description carries the burden of describing return values and does so field-by-field, including nested attendee structure and explicit omissions. For a read-only, 3-param tool this is nearly complete; only visibility/permission limits on which events are retrievable are unstated.

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

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

Schema description coverage is 100% and all three parameters are documented there, including the 'primary' calendar_id convention and the source of event_id. The description adds no syntax or format 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 and resource ('Fetch full details of a calendar event') and immediately enumerates what 'details' means (attendees, description, location). It also names the sibling it is not, calendar_list_events, 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?

Explicitly redirects discovery to calendar_list_events and notes the user-approval requirement, which is a real gating condition. It stops short of stating when-not to use this tool (e.g. permissions or visibility limits), so it is clear context without full exclusions.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description still adds meaningful context beyond them: the auto-approval status and the exact return shape ('Returns {visibility}'). It does not cover auth requirements or rate limits, but for a simple read tool this is solid.

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 with zero waste; the core purpose and scope-limiting clause are front-loaded, followed by return shape, alternative tool, and approval note. 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?

The tool is low-complexity, the schema is fully documented, and there is no output schema. The description fills the remaining gap by stating the return shape and the auto-approval behavior, so 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 100%, so the schema already documents all three parameters (calendar_id, event_id, reason) in detail. The description adds no syntax, format, or constraint details beyond what the schema provides, making the baseline of 3 appropriate.

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

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

States a specific verb and resource ('Get a calendar event's visibility setting'), lists the possible values, and explicitly distinguishes itself from the sibling calendar_get_event_details by scope. An agent can identify what this tool does 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?

Explicitly names the alternative for fetching full details (calendar_get_event_details) and the alternative for mutation (calendar_set_event_visibility), giving clear when-to-use routing. Nothing is left to inference about which sibling to pick.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the events-vs-free_busy fallback when access is unavailable, the privacy-settings degradation that can reduce events to busy slots, the 50-event cap, and that calls are auto-approved. This is unusually rich behavioral 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?

Front-loads purpose and fallback logic, then the routing hint, then return shapes. Dense but each part earns its place; the return-shape enumeration is slightly heavy but justified given no output schema exists.

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

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

For a read-only tool with no output schema, the description fully specifies the three possible return shapes (events, free_busy, error), the 50-event cap, and privacy degradation. Nothing needed to call or interpret it correctly is missing.

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

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

Schema description coverage is 100%, so all four params (emails, time_min, time_max, reason) are already documented in the schema. The description adds no extra syntax or format guidance beyond the return-shape context, 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 ('Query colleagues' schedules for a time range') and explicitly scopes it to other people's calendars rather than the user's own. It names the sibling it is not (calendar_list_events) so an agent can distinguish them without opening schemas.

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

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

Gives explicit use context ('Use this for meeting scheduling') and a named alternative with the selection condition ('Use calendar_list_events instead for the user's own calendar'). Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the exact return shape and the 'Auto-approved' note indicating no human approval gate. It says nothing about pagination or empty-result behavior, 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 the purpose, then the return shape, then the downstream usage hint. Every sentence carries distinct information with no 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?

No output schema exists, and the description compensates by naming the returned fields. Combined with the trivially simple one-parameter input and the annotation safety profile, an agent has everything needed to call this tool correctly.

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

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

One parameter with 100% schema description coverage, so the schema fully documents the required 'reason' field. The description adds no information about that parameter (its 'id as calendar_id' remark concerns output usage elsewhere), 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 ('List all Google Calendars for the authenticated user') and even enumerates the returned fields {id, summary, primary, access_role}, which cleanly separates it from siblings like calendar_list_events or calendar_list_colors.

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 describes the downstream workflow: 'Pass an id as calendar_id to calendar_list_events and the other calendar tools.' This tells the agent when this tool is the prerequisite step. It lacks an explicit when-not-to-use or a named alternative for listing calendars another way, so it falls 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, so safety is covered. The description adds real context beyond that: the palette is fixed, results are sorted by id in the range 1-11, and the call is auto-approved (no approval round-trip). It stops short of detailing error or edge behavior, 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 tight sentences: what it returns, why you'd call it, and the exact return shape. The useful routing information is front-loaded with 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?

With no output schema present, the description compensates by naming the exact return shape and ordering ({id, name, background, foreground}, sorted 1-11). For a simple read-only lookup tool, nothing an agent needs to invoke or consume it correctly is missing.

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

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

Schema description coverage is 100% and the only parameter (reason) is fully documented in the schema, so the schema carries the parameter burden. The description adds no syntax or format detail for the parameter, which matches the baseline-3 expectation when coverage is high.

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 (List) and resource (Calendar's fixed event color palette), then enumerates exactly what each entry contains (id, name, hex background/foreground). It is easily distinguished from siblings because it explicitly names the consumers of its output (calendar_create_event, calendar_update_event, calendar_set_event_color).

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 precise condition for use: call this before passing a color argument rather than guessing a numeric id. It names the exact alternative tools that consume the returned id/name, leaving no inference to the agent.

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; the description adds meaningful behavior beyond that: exact return shape, recurring-event expansion, start-time sorting, pagination behavior ('reads up to max_results events across pages'), and an 'Auto-approved' note. The safety profile is covered by annotations, so the marginal value is in these operational details.

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-loads the verb and resource, then return shape, then routing. It is somewhat dense with parenthetical field lists, which borders on redundancy, but every clause about behavior (recurring expansion, sorting, pagination) 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?

Covers the essential ambiguity for a list tool: what is returned, what is deliberately withheld, how recurring events are handled, pagination limits, and where to go for details. With no output schema, this description carries the return-value burden adequately.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions the return fields but does not add syntax details for time_min/time_max, query matching, or max_results beyond what the schema already documents, so it does not improve on the schema's parameter documentation.

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 events from a calendar) and enumerates the returned fields. It distinguishes itself from calendar_get_event_details by defining the two tools' complementary scopes 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?

Explicit routing: 'Use calendar_get_event_details to read one event's attendees and description, or calendar_list_calendars to find calendar_id.' It also states when data is not returned (no attendees, description, or links), which tells the agent when to switch 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 safe read-only/idempotent profile, and the description adds substantial extra context: it is a locally-cached directory refreshed by a sync script, it is not a live Workspace lookup, it may return empty, and results are unpaged. These are exactly the operational caveats 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?

Four dense sentences, each carrying distinct payload (scope, cache caveat, return shape, next steps), with the definition front-loaded and 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?

With no output schema, the description compensates by enumerating the returned fields and stating that results are unpaged. Combined with the safety annotations and full schema coverage, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so both the query filter and the reason parameter are already documented in the schema; the description adds no syntax or format detail beyond that. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List meeting rooms and resource calendars') and names the source directory, which cleanly separates it from the sibling calendar_list_calendars. An agent knows exactly what set of entities this returns.

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: use calendar_get_free_busy with the resource_email to check availability, and use the room email with calendar_create_event/calendar_update_event to book. This is a full when-to-use and what-next chain, not just 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 it is neither read-only nor destructive, and the description adds genuinely new behavioral context: the mutation is strictly limited to the color field, it returns {id, title, color_id}, and it requires user approval — none of which the annotations convey.

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

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

Three tight sentences, each carrying a distinct payload (scope, input format plus sibling reference, return shape plus approval), with the core action front-loaded. 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?

With no output schema, the description supplies the return shape, the approval requirement, the color value domain, and the lookup sibling for valid values. For a 4-parameter mutation tool this covers everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so all four parameters (including the reason field) are already documented in the schema. The description's restatement of the color id range (1-11) or name adds no syntax or format detail beyond what the schema already provides.

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

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

States a specific verb and resource (set a calendar event's color) and immediately scopes it: 'Only the color changes — no other fields are affected.' That scope statement cleanly distinguishes it from the broader calendar_update_event sibling.

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

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

It routes the agent to calendar_list_colors for valid color values and flags that user approval is required, which is useful implicit guidance. However, it never states when to prefer this over calendar_update_event or what conditions make it inappropriate, so usage is only implied.

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

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

Annotations only declare the generic write profile (readOnly=false, idempotent=false, destructive=false); the description adds real context beyond them: the exact scope of mutation, that other fields are untouched, the return shape {id, title, visibility}, and that user approval is required. No contradiction with 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?

Front-loaded with the action and scope, then the value semantics, then the return shape and approval note. Every sentence carries information, though the four-value enumeration makes it longer than strictly needed for a single-field mutation.

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 stating the return shape, and it covers the mutation scope, approval requirement, and the read counterpart. Nothing an agent needs to call this correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by defining the semantics of each enum-like value ('default' follows calendar sharing, 'public' is visible to calendar viewers, 'private' hides details, 'confidential' is a legacy synonym), which the schema only lists without explaining.

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 visibility') and immediately scopes it ('Only visibility changes — no other fields are affected'), which cleanly separates it from calendar_update_event and calendar_set_event_color. It also routes to calendar_get_event_visibility for reading the current value.

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 names the read alternative ('Use calendar_get_event_visibility to read the current value') and notes the approval prerequisite. It does not state when-not to use it (e.g., bulk changes or events the user cannot edit), so it stops short of full when/when-not guidance.

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

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

Annotations only declare the safety flags; the description adds materially more: the day's existing entry is replaced (overwrite semantics), a specific return shape {id, start_time, end_time, html_link} is given despite no output schema, and 'Requires user approval' discloses an approval gate the annotations do not mention.

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: action and scope first, overwrite/return behavior second, alternative routing and approval last. No filler, everything front-loaded.

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 mutating tool with no output schema, the description supplies the overwrite behavior, the approval requirement, and the return fields, while the schema fully covers inputs. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all parameters (date, location, label, building_id, reason) are already documented in the schema. The description adds the web-UI-picker analogy but no per-parameter syntax, 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 ('set your working-location presence ... for a single day on the primary calendar') and scopes it to one day. It also equates the operation to 'the same picker Google Calendar's web UI exposes', making the action unambiguous and separable from the many other calendar_* 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?

Explicitly routes away from the closest alternative ('Use calendar_create_out_of_office for time off') and constrains scope to a single day, so the agent knows both when this tool applies and which sibling handles the neighboring case.

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

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

Adds substantial context beyond the annotations (readOnly=false, idempotent=false, destructive=false): partial-update semantics ('Only the fields you pass non-empty change'), a hard limitation ('guests cannot be edited here'), the exact return shape including conference_link, and an explicit 'Requires user approval' gate. These are exactly the behavioral facts an agent cannot derive from the schema or 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?

Front-loads purpose, then scope semantics, then mutation/return behavior – a logical order with no filler sentences. It is a dense single paragraph, though, and the three-way scope explanation would scan faster as a short list; a small structure cost.

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

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

For a 13-parameter mutation tool with no output schema, the description covers the mutation model, the one ambiguous parameter's real-world effect, an unsupported operation, the return fields, and the approval requirement. Nothing an agent needs 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?

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining what 'scope' actually does to a recurring series ('following' splits the series, leaving earlier occurrences untouched) – detail not present in the schema's terser enum explanation. Other parameters are left to the schema, which is adequate 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?

Opens with a specific verb+resource ('Update an existing calendar event') and explicitly distinguishes itself from the color/visibility-only siblings by naming calendar_set_event_color and calendar_set_event_visibility. An agent can route to or away from 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 clear conditional guidance: use the dedicated color/visibility tools when only those fields change, and it explains when each 'scope' value applies. It does not state prerequisites (e.g., required permissions) or when to prefer create/delete over update, so it falls short of full when/when-not coverage.

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

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

Goes well beyond the readOnly/idempotent/destructive annotations: it discloses that CQL is passed through verbatim, that result ordering follows the CQL (with an ordering tip), the result cap, and that excerpts may be redacted by user privacy settings. These are real behavioral traits the annotations do not convey.

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

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

A single dense paragraph that front-loads the purpose and contrast before the return shape and limits. It is longer than typical, but nearly every clause carries operational information; only the duplicated max_results default/cap is redundant with 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?

With no output schema, the description compensates by enumerating the returned fields ({id, title, content_type, space_key, space_name, excerpt, url}) and their ordering, plus the redaction caveat. Nothing needed to call or interpret this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value with the ordering hint ('add order by lastmodified desc for newest first') and confirms the default/cap semantics for max_results, plus notes the exact-query pass-through behavior of cql. It does not explain the 'reason' parameter, but that is self-evident from 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 ('Search Confluence using CQL') and immediately contrasts it with the sibling it is not equivalent to, naming confluence_search explicitly. An agent can distinguish this from confluence_search 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?

Gives both a when-to-use (CQL-based filtering by space, type, label, creator, date) and a when-not (plain keywords -> use confluence_search instead), naming the alternative explicitly. The 'Auto-approved' note further clarifies it needs no approval gate.

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, so the safety profile is partly covered. The description adds genuinely new context: the return value shape ('same shape confluence_get_page returns'), that a new id is assigned, and that user approval is required. It does not restate the non-idempotent nature, but the approval requirement is a meaningful addition.

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, each carrying distinct information (purpose, body format, return shape, alternative tool, approval requirement) with the core action front-loaded. No filler or restated name/title.

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 compensates by describing the returned object and its new id, redirects to the correct sibling for edits, and flags the approval gate. Combined with full schema coverage and annotations, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and five parameters are all documented in the schema, so the schema is doing the heavy lifting, which sets a baseline of 3. The description only echoes the body-format fact ('Body is HTML storage format') that the schema already specifies in more detail, adding no syntax or format meaning beyond structured fields.

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

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

States a specific verb and resource ('Create a new Confluence page') plus the scope ('in the given space'), and explicitly distinguishes itself from the sibling confluence_update_page. An agent can differentiate create vs update 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?

Names the alternative tool and the exact condition that selects it ('to change a page that already exists'), and notes the user-approval prerequisite. This is explicit when-to-use/when-not guidance rather than inferred 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: divergent local vs organization-managed delivery (file path vs inline bytes vs one-time link), the differing return shapes, and the user-approval requirement. This is unusually rich behavioral disclosure.

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 layered with identification, the local/managed branch, return shapes and approval. Dense but every clause carries information; only slight verbosity in restating destination_dir behavior already in 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 download tool with no output schema, the description fully covers return values ({path, name, size_bytes} vs inline/link), the install-dependent behavior, and approval requirements. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents each parameter in detail, including destination_dir's local-vs-managed semantics. The description largely restates this, so it adds little parameter-level meaning beyond the structured fields. 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 ('Download a Confluence page attachment's content') and immediately routes the agent to the sibling that produces the needed identifier (confluence_list_attachments). An agent can tell it apart from confluence_list_attachments 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?

Explicitly says how to identify the attachment (name from confluence_list_attachments), and gives conditional guidance: on a local install pass ~/Downloads for a deliverable vs a scratch dir to just read/process; on a managed install destination_dir is ignored. Clear when-to-use and what-value-to-pass 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 cover read-only/idempotent/non-destructive, but the description adds real behavioral value: 'email addresses are never returned', the returned field set, the max_results cap, and that the tool is 'Auto-approved' (no gated approval). That goes beyond what structured fields declare.

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 compact sentences, each carrying distinct information (purpose, return shape/privacy, approval status, alternative tool). Slightly dense, but front-loaded with the core capability and free of 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?

With no output schema present, the description fully carries the burden by spelling out the returned record shape and the max_results bound. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so query/reason/max_results are already documented. The description reinforces the query semantics (name or email) and the privacy constraint on email output but adds little syntax or format 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+resource+scope: 'Find Atlassian users by name or email and return their account ids.' It also explicitly disambiguates against the closest sibling by saying to use confluence_search for pages, not people.

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

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

Gives clear when-to-use context ('mention someone in a page body by writing @[Name](accountId)') and names the alternative for page lookup. It does not mention the parallel jira_find_users sibling, leaving a small inference gap for Atlassian-wide vs Confluence-scoped lookups.

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 side effects are covered. The description adds a non-annotation behavioral fact – 'Requires user approval' – plus a detailed return shape. It stops short of noting rate limits or pagination, but adds real value beyond 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?

Front-loads the core action, then the return shape, then the alternative. Efficient overall, though the inline enumeration of every return field is slightly heavy and 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?

With no output schema, the description takes on the burden of describing the return object and its fields (id, title, version, author, mentions) — which it does thoroughly — and covers the approval requirement and the alternative route. Complete for an agent to call 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 page_id and reason are already documented in the schema. The description only restates that the fetch is by page ID, adding no format or edge-case detail. Baseline 3 applies when the schema carries the parameter semantics.

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

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

States a specific verb (Fetch) plus resource (Confluence page) and the identifier used (page ID), and disambiguates from the sibling confluence_get_page_by_title. An agent can select 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?

Explicitly names the alternative (confluence_get_page_by_title) and the condition that selects it: you know space and title but not the id. Routing is unambiguous.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds meaningful context beyond that: the return shape (same as confluence_get_page, body included), error semantics on missing title, and an approval gate ('Requires user approval'). This is substantive behavioral disclosure.

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 purpose, then return/error behavior, then the alternative. No filler or redundancy.

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

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

With no output schema present, the description compensates by explaining the return shape and error behavior, and it flags the approval requirement. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so all three parameters (space_key, title, reason) are already documented in the schema, including the exact-match constraint and the space-key origin. The description merely restates 'space key and exact title' and adds no syntax or format meaning beyond the schema. Baseline 3 is correct.

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

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

States a specific verb+resource+lookup key: 'Fetch a Confluence page by space key and exact title.' It explicitly distinguishes itself from sibling confluence_get_page by id, so an agent can route 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?

Gives an explicit alternative and the condition that selects it: 'Use confluence_get_page instead when you already have the page id.' It also discloses the boundary condition (errors when no page has that title), which tells the agent when this lookup will fail.

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 safe read profile; the description goes well beyond by disclosing auto-approval status, that only metadata (not content) is returned, the 500-attachment cap, and that names may be redacted by user privacy settings. These are exactly the operational caveats an agent needs and cannot get from the structured fields.

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

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

Three tight sentences: purpose and content scope first, return shape and limits second, sibling routing last. No filler, nothing restated from the schema.

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

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

No output schema exists, so the description compensates by spelling out the return structure ({page_id, attachments:[{name, media_type, size}]}) plus cap and redaction behavior. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and both parameters (page_id, reason) are fully documented in the schema, including where page_id comes from. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

States a specific verb and resource — listing attachment names, media types, and sizes for a Confluence page — and explicitly distinguishes itself from confluence_download_attachment, which fetches the actual file. An agent can tell it apart from siblings 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?

Clearly routes the agent to confluence_download_attachment when the actual file is needed, and the 'metadata only, no attachment content' note tells the agent what this tool will not give it. It stops short of explicit when-not conditions or prerequisite context, but the alternative is named directly.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: results exclude page bodies, are returned in the API's order, and are capped by max_results (default 20, max 1000), plus the note that author is an opaque Atlassian account id while author_name is resolved. It stops short of stating auth/permission requirements, so it is strong but not exhaustive.

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

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

Front-loaded with the core action and result, followed by behavioral notes and routing guidance. Every clause carries information, though the max_results default/cap repeats the schema and the trailing 'Auto-approved.' is peripheral.

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 takes on the burden of describing return shape and does so (field list, no bodies, ordering, author vs author_name). Combined with the sibling routing, 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 100%, so space_key, max_results, and reason are all documented in the schema itself, including the same default/cap wording the description repeats. The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('List pages in a Confluence space'), scopes it to a space, and enumerates the returned identity fields (title, id, version). It cleanly distinguishes itself from confluence_search and confluence_get_page, so an agent can pick it 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 names two alternatives and the condition selecting each: confluence_search 'to find pages by words' and confluence_get_page 'to read one'. When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds value beyond them: the exact return shape, the max_results cap of 1000, and the 'Auto-approved' note that no approval gate applies. It does not discuss pagination or error behavior.

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

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

Three compact sentences, front-loaded with the resource and scope, then return shape, then the alternative. 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 usefully spells out the returned fields, and it covers the cap and the sibling routing. Nothing essential 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 description coverage is 100%, so the schema already documents space_type and max_results (including the default 50 / cap 1000 the description repeats). The description adds no meaning beyond the schema and does not mention the required 'reason' parameter, so baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (Confluence spaces) with scope ('the user has access to') and enumerates the returned fields. It also routes the agent to confluence_list_pages for the natural next step, so it is distinguishable from siblings.

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

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

The description gives a clear use context and names confluence_list_pages as the follow-up for drilling into pages, which helps the agent sequence calls. It stops short of explicit when-not conditions (e.g., use confluence_search instead when looking for a specific space by name).

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds key behavioral context: it explains the 7-day auto-refresh cycle and indicates the operation is auto-approved. It also states the return value. However, it doesn't discuss potential rate limits or the scope of the cache (e.g., does it affect all users or just those in the current workspace?).

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

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

The description is a tight, information-dense set of sentences. It front-loads the purpose, then adds usage conditions, return value, and an alternative tool. No extraneous 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 one-parameter tool with full schema coverage and annotations, the description covers purpose, usage, and return value. It doesn't explain what PrivacyFence's cache contains or how long the refresh takes, but these are minor gaps. No output schema exists, so the description appropriately notes the return format.

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

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

Schema description coverage is 100%, and the single parameter 'reason' is fully documented in the schema. The description adds no parameter-specific information, which is appropriate since the schema handles it. Baseline 3 is correct.

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

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

States a specific verb and resource: 'Re-fetch the names of every Atlassian account id PrivacyFence has cached.' This is unambiguous and distinct from read-oriented siblings. It differentiates itself from confluence_find_users by describing different functionality.

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

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

Explicitly states when to use it ('when a renamed or newly added person shows up wrong') and provides a clear alternative ('Use confluence_find_users instead to look up someone by name'). Also notes that cached names refresh automatically after 7 days, clarifying when the manual call is unnecessary.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantially more: result ordering (most recently modified first), the result cap and default, the fact that excerpts may be redacted by privacy settings, the exact CQL rendering of the query, and the 'Auto-approved' note. These are behavioral traits the annotations cannot convey.

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

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

Dense but front-loaded: purpose first, then result contract, then routing guidance, then approval note. It is a single long semicolon-chained paragraph, which is slightly heavy to parse, but 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 carries the return-value burden, and it does so fully: result fields, order, cap, and excerpt redaction caveat. Combined with a 100%-covered input schema and read-only annotations, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents query, reason, and max_results. The description largely repeats the default/cap and plain-text nature, but does add the exact CQL wrapping ('text ~ "<query>" (no operators)'), which meaningfully explains how the input is transformed. Marginal but real added value over the schema.

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

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

States a specific verb and resource: 'Full-text search across Confluence content.' It immediately distinguishes itself from the sibling confluence_cql_search by scoping this to plain-text queries, 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?

Names the alternative explicitly ('use confluence_cql_search to filter by space, type, label or date') and names the natural follow-up ('Get the page with confluence_get_page'). The when-to-use / when-not-to-use boundary is fully specified.

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

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

Adds real value beyond annotations: the body format (HTML storage format), the omitted-field semantics ('an empty body no longer clears the page'), the return shape (same as confluence_get_page, incl. new version number), and the approval requirement. Annotations only signal non-readonly/non-idempotent.

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 purpose, then mutation semantics, then return shape, then the prerequisite call and approval note. No filler; every sentence earns its place.

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

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

For a 4-param mutation tool with no output schema, it covers format, defaults, return shape, prerequisite read, and approval. Minor gaps: no note on conflict/version handling for concurrent edits, and destructiveHint=false is not reconciled with whole-body replacement.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including field defaults and the @-mention syntax. The description reinforces the omitted-field behavior but adds little the schema doesn't already carry.

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 (update) and resource (existing Confluence page) with the exact mutable fields (title/body). Clearly distinguishes from confluence_create_page and confluence_get_page, which appear as 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?

Explicitly says to call confluence_get_page first to read current content, and explains the both/neither semantics of title/body. It doesn't name a when-not-to-use case (e.g., title collisions), but context is otherwise clear.

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 and destructiveHint=false. The description adds real value beyond them: it discloses the return shape {resource_name, label_added}, the case-insensitive name matching, the auto-create side effect, and a user-approval requirement. It doesn't cover failure modes (e.g., nonexistent contact), keeping it from a 5.

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

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

Front-loaded with the core action, then layered with return shape, matching rule, alternative tool, and approval requirement. Every sentence carries distinct information with no filler.

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

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

No output schema exists, yet the description supplies the return shape, so the agent knows what comes back. Combined with the approval requirement and matching semantics, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100% and the schema already documents all three params, including that an unknown name creates a new label. The description's only added semantic is that labels match by name case-insensitively, which is useful but marginal, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Add a label to a contact') and immediately clarifies the auto-create behavior. It also names the sibling contacts_remove_label, so an agent can distinguish it from related contact 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?

It names the inverse tool (contacts_remove_label) as the alternative and states the prerequisite 'Requires user approval.' However, it doesn't give explicit when-to-use vs when-not conditions beyond the inverse operation, so it falls just short of the top band.

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 and idempotentHint=false, so the write/non-idempotent profile is already covered. The description nonetheless adds real value beyond them: it discloses that user approval is required, that deletion is not supported, that duplicates are a risk mitigated only by searching first, and the exact shape of the return value ('the same shape contacts_get returns'). It stops short of failure modes or rate limits, so a 4 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?

Five short sentences, each earning its place: action, approval requirement, parameter format caveat, scope limit, return value, and the duplicate-avoidance step. The core action is front-loaded and nothing is padded.

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

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

There is no output schema, but the description compensates by describing the return ('the created contact, with its new resource_name'). For a 7-parameter mutation tool with an approval gate, this covers what an agent needs, though it says nothing about validation failures or what happens if a duplicate is created anyway.

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 7 parameters are already documented in the schema, including the JSON-string format for emails/phones. The description repeats the emails/phones JSON example verbatim, which is restating structured data rather than adding new meaning; the baseline of 3 applies.

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

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

States a specific verb and resource ('Create a new contact in the user's Google address book') and immediately differentiates itself from the sibling read tools by telling the agent to use contacts_search first to avoid duplicates. An agent can tell it apart from contacts_get/contacts_update/contacts_list 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?

Explicit when-to-use (creating a new contact), an explicit alternative workflow ('Search with contacts_search first to avoid creating a duplicate'), and an explicit when-not ('Contact deletion is not supported'). Nothing about tool selection is left to inference.

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

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

Beyond the readOnly/idempotent annotations, the description discloses three non-obvious behaviors: the call fails if the contact's kind does not match 'source', notes may be redacted by the user's privacy settings, and the response matches the contacts_list shape. It also states the tool is auto-approved, which matters for the approval flow.

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 and every sentence carries information, but the semicolon-heavy, multi-clause sentences reduce scannability, and 'Auto-approved.' reads as an appended fragment rather than integrated guidance.

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

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

For a read-only single-record fetch with a fully documented 3-parameter schema and no output schema, the description supplies everything needed: identifier format and source, failure semantics, redaction caveat, and response shape parity with contacts_list.

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 resource_name and source are already fully documented in the schema; the description largely restates them. The failure-on-mismatch detail for 'source' is the only added semantic value beyond the 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 gives the exact identifier format ('people/c12345'), which unambiguously separates it from contacts_list and contacts_search. An agent can immediately tell this is a single-record lookup.

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 supplies the prerequisite and routing guidance ('Get the resource name from contacts_search or contacts_list'), making the intended call sequence clear. It stops short of naming an explicit when-not case (e.g. use contacts_search when you only have a name), so it is clear context rather than full when/when-not 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, and the description adds genuinely new behavioral facts: that personal and directory sources are blended by default, that notes may be redacted by the user's privacy settings, that reads page across pages, and that 'source' is applied before counting toward max_results. It even states the tool is auto-approved, which matters for an agent deciding whether to call it.

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

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

The description is front-loaded with the core action and the key gotcha (source blending) before the return-shape enumeration. It is dense and slightly long, but each sentence 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?

With no output schema, the description compensates by enumerating the full returned field set and the possible 'source' values, plus the notes-redaction caveat. For a 3-parameter read tool with full annotation coverage, nothing material 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 100%, so baseline is 3, but the description adds meaning the schema lacks: what 'both' actually means ('a saved contact who is also a colleague') and the ordering rule that 'source' is applied before counting max_results. The 'reason' parameter is not discussed, minor omission.

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 + resource ('List contacts from the user's Google address book') and immediately clarifies the scope nuance (personal vs. Workspace directory blending). It distinguishes itself from contacts_search by name, so an agent can route 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 names the alternative explicitly ('Use contacts_search instead to find a contact by name or email') and gives the condition selecting it. It also explains how to use 'source' to split the two contact pools, which is actionable guidance for the common ambiguity.

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, which correctly signals mutation without deletion. The description adds valuable specifics: return shape {resource_name, label_removed}, behavior on missing label ('nothing changes then'), and a 'Requires user approval' constraint. One gap: it doesn't explain why idempotentHint=false (repeated calls could error), but overall good coverage above 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 covering action, return value, edge case, sibling reference, and approval requirement. Front-loaded with the core action. Slightly dense but no wasted words; could separate the approval requirement for better scannability.

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-param mutation with no output schema, the description covers return structure, edge-case behavior, sibling tooling, and approval requirement. It stops short of explaining permission requirements or error conditions beyond 'label not found', but given annotations and full schema coverage, it is largely complete.

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

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

Schema coverage is 100%, so all three parameters are fully documented in the schema (including case-insensitivity of label_name and the fact that the label itself isn't deleted). The description does not add syntax or usage details beyond what the schema already provides, so baseline 3 is appropriate.

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

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

States a specific verb ('remove') and resource ('a label from a contact'), and explicitly names the inverse sibling 'contacts_add_label' to clarify direction. An agent can immediately distinguish this from add_label or gmail_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?

References 'contacts_add_label' as the complementary operation, giving directional context. However, it does not explicitly state when to use this tool vs. alternatives like contacts_update (which might also modify labels) or provide preconditions/exclusions.

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

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

Annotations already cover safety (readOnly/idempotent/non-destructive), yet the description adds substantial behavioral context: the non-obvious 'both' default resolves to saved contacts only, directory results are limited to profiles with existing contact history, notes may be redacted by privacy settings, and the call is auto-approved. That is well beyond what the annotations 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?

Dense but front-loaded: the core action and its sibling routing come first, caveats second, return shape last. Every clause carries distinct information, though the return-shape sentence is long and could be tightened.

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 takes on the burden of describing returns (list of contacts shaped like contacts_list, source values 'personal'/'directory'/'both'/'other', max_results bound, possible redaction) and does so. Nothing needed to call this correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real nuance the schema does not spell out — that the default 'both' means saved contacts only, and that directory is a scan rather than a filter. It also reinforces the differing max_results caps (30 saved vs 1000 directory). Slight redundancy with the schema keeps it off a 5.

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') and immediately distinguishes itself from the two nearest siblings, contacts_list and contacts_get, by naming both and their conditions. An agent can select it 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?

Explicit when-to-use routing: 'Use contacts_list instead to browse without a query, and get a contact's full record with contacts_get.' It also states a hard limitation (no full company-directory search under this app's permissions), which is exactly the kind of guidance that prevents a doomed call.

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

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

With annotations only covering readOnly/idempotent/destructive, the description adds real behavioral context: the user-approval gate, the partial-update rule (empty leaves a field unchanged), the special '[]' clearing semantics for list fields, and the exact return shape referencing contacts_get. That is exactly the kind of beyond-annotation detail the score 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?

The core action and partial-update rule are front-loaded, followed by the format example, then return shape, then prerequisites. Every sentence carries operational value with no filler.

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

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

For an 8-parameter mutation with no output schema, the description covers approval requirement, replacement/clearing behavior, JSON string encoding, and the return shape. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents resource_name, each field, defaults, and the emails/phones JSON format and clearing rules. The description restates that same content rather than adding new semantics, 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 ('Update a contact's fields') and immediately distinguishes the operation from creation/read siblings by explaining partial-update semantics. An agent can tell it apart from contacts_create and contacts_get 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 prerequisites and workflow: get resource_name from contacts_search, read current values with contacts_get first, and note that user approval is required. It does not state when NOT to use the tool, so it falls just short of the top band.

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

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

Goes well past the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false): it discloses the posting identity ('posted as the user'), the anchoring behavior ('not anchored to any text'), the approval requirement, and the returned fields including how comment_id is obtained. These are exactly the behavioral traits an agent needs before invoking a write 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 short sentences, zero filler, and the core action is front-loaded before the return contract. Each sentence carries distinct information (action, result, behavior/prerequisite).

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 low-complexity, three-parameter write tool with no output schema, the description supplies the result shape inline and covers the non-obvious behaviors (identity, anchoring, approval). Nothing essential 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 description coverage is 100%, so file_id, comment and reason are already fully documented in the schema (including how to obtain the file id). The description adds no format, constraint or default information beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Add a comment to a Drive file') and immediately follows with the return shape, so the agent knows exactly what operation is performed and what comes back. There is no competing Drive comment tool among the siblings, so no further disambiguation is required.

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

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

Usage is implied rather than spelled out – nothing says when to prefer this over other communication tools (e.g. slack_send_message or jira_add_comment) or when not to comment on a file. The only contextual cue is the prerequisite 'Requires user approval', which usefully signals a gated workflow but is not framed as when-to-use guidance.

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

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

Annotations only cover the safety profile (write, non-idempotent, non-destructive); the description adds materially more: the original is left unchanged, folders are rejected, user approval is required, and the full return shape is enumerated with the meaning of 'id'. That is rich behavioral context an agent can act on.

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

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

Six short sentences, front-loaded with purpose, then behavior, limits, prerequisite, and approval requirement, with no filler. The return-shape sentence earns its place because no output schema exists.

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

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

For a mutation tool with no output schema, the description covers purpose, source preservation, limitations, prerequisite, approval, and the exact return fields. 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?

Schema coverage is 100%, so all four parameters are already documented in the schema. The description echoes the destination-id source and clarifies that the returned id is the new copy's, but adds little syntax or format 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 ('Copy a Drive file into a folder'), plus scope limitations ('Folders cannot be copied'). This clearly separates it from siblings like drive_move_file, drive_upload_file, and drive_create_blank_file 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 prerequisites explicitly: the destination id comes from drive_list_folder, and the call 'Requires user approval.' It also states the negative constraint that folders cannot be copied. It does not name an alternative sibling for the move-vs-copy decision, so it stops 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=false, idempotentHint=false, destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the return shape {id, name, mime_type} and the 'Auto-approved' approval behavior, which annotations don't express. It doesn't state permission requirements or what happens on name collisions, so it's 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 compact sentences, front-loaded with purpose and return shape before the routing guidance. Every sentence earns its place; the only nit is that the routing list slightly crowds the core statement.

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

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

For a four-parameter creation tool with full schema coverage and no output schema, the description supplies what the schema cannot: the return shape and the downstream 'fill it' workflow that prevents the agent from creating a dead-end empty file. It omits permission scope and collision behavior, keeping it short of complete.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including MIME type examples and the empty-string default for parent_folder_id. The description adds no parameter-level syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource ('Create a new blank Drive file') and explicitly distinguishes itself from siblings by naming which tool to use next depending on file type (drive_write_doc_content, drive_write_file_content, drive_upload_file) and calling out drive_sheets_create for spreadsheets. An agent can pick this tool 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?

Explicitly routes the agent: use this to create the empty shell, then fill it with one of three named tools, or use drive_sheets_create for spreadsheets. The 'Auto-approved' note also tells the agent it needs no approval gate, which is a usage condition. Nothing is left to inference.

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

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

Goes well beyond the annotations (which only say non-readonly, non-idempotent, non-destructive): discloses the failure mode when find_text is not unique, the return shape {file_id, occurrences_replaced}, that empty replace_markdown deletes the match, and that user approval is required.

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

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

Front-loaded with the core operation, and every sentence carries information, but the find_text sentence is a dense run of em-dashes and parentheticals that takes effort to parse.

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

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

For a 5-parameter mutation tool with no output schema, the description covers preconditions, alternatives, side effects, and the return value, leaving nothing an agent needs missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: it warns that find_text must come from plain unformatted text, not drive_get_file_content's Markdown rendering, and explains replacement Markdown syntax including GFM pipe tables.

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 (replace), resource (existing text in a Google Doc), and scope (one occurrence, rest untouched). It is immediately distinguishable from siblings like drive_write_doc_content and drive_docs_format_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?

Explicitly routes the agent: use drive_docs_format_content to change formatting without changing text, and replace_all=true to replace every occurrence. It also states the preconditions for a successful match (exact plain-text, unique, enough surrounding context) and notes user approval is required.

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

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

Annotations establish the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds genuinely non-obvious behavior: every formatting param is opt-in with 'leave unchanged' defaults, and the return shape {file_id, occurrences_formatted}. It does not cover failure modes beyond what the schema's replace_all note provides, so it stops short of a 5.

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

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

Front-loaded with purpose and scope, then defaults, then return value and the sibling pointer. Every sentence carries information, though the opt-in explanation is slightly verbose relative to the schema note that already says 'omit to leave unchanged'.

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 supplies the missing return shape, the opt-in default contract, the approval requirement, and sibling routing. 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 100%, so the baseline is 3, but the description adds real meaning on top of the schema by explaining the opt-in default semantics (setting only highlight_color leaves bold/italic untouched), which clarifies how the empty-string defaults interact.

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), the resource (existing text in a Google Doc), the exact formatting kinds (bold, italic, highlight, text color), and explicitly distinguishes itself from drive_docs_edit_content by noting it does not change the text itself.

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 routing: use this for formatting, use drive_docs_edit_content to change the text itself, and states that user approval is required. The alternative and the selection condition are both named.

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

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

Annotations cover the safety profile (readOnly/idempotent/non-destructive), but the description adds substantial context they cannot: the local-install vs organization-managed install split, that destination_dir is silently ignored on managed installs, that large files return a one-time link the human must open, and the exact return shape {path, name, size_bytes, truncated}.

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

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

Front-loaded with purpose and the export caveat; every sentence carries real information about install types, return shape, and approval. It is dense and slightly repetitive, restating destination_dir guidance that the schema already covers, but nothing is wasted 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?

With no output schema, the description supplies the return fields itself, and it covers the environment-dependent behavior that would otherwise cause a wrong call (saving to an ignored directory on managed installs). Nothing material is missing 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 100%, so the baseline is 3 and the schema already documents destination_dir's semantics. The description nonetheless reinforces the deliberate-choice framing for destination_dir and ties it to the install-type behavior, adding decision guidance beyond the field docs, though the overlap with the schema text is substantial.

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 adds the scope-defining behavior that Workspace docs are exported as text/CSV. It names the sibling it is not (drive_get_file_content) so an agent can differentiate without opening other schemas.

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

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

Explicitly routes the agent: 'Use drive_get_file_content instead to read a file's text,' and gives a concrete decision rule for destination_dir (deliverable path vs scratch directory). It also warns that user approval is required, which is a usage precondition, not just a behavior.

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, yet the description adds substantial context beyond them: the exact returned Markdown syntax, truncated:true on cut output, highlights/text_colors side-fields, placeholder behavior for images, and that content may be redacted by privacy settings. It also notes the approval requirement, which annotations do not convey.

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

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

Purpose is front-loaded in the first sentence, followed by format-by-format behavior. The long parenthetical enumerating Markdown syntax is dense but arguably earns its place as round-trip guidance; slightly verbose but no wasted framing.

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

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

With no output schema, the description carries return-shape information thoroughly: {file_id, content} plus truncated/highlights/text_colors, per-format return types, and edge cases (scanned PDFs, redaction). Nothing essential 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 description coverage is 100% and both parameters (file_id, reason) are already documented in the schema, including the id's origin from drive_list_files/drive_list_folder/URL. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Fetch the content of a Drive file by id') and immediately disambiguates from siblings by describing what each file type returns. An agent can distinguish it from drive_get_file_metadata and drive_download_file 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 unsupported types to drive_download_file ('Other files, such as images, only get a placeholder: use drive_download_file for those') and notes format suitability for round-tripping into drive_write_doc_content/drive_docs_edit_content. It gives clear context but does not contrast against metadata/list siblings like drive_get_file_metadata or drive_sheets_get_values.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, yet the description adds valuable behavior: the exact return shape, the privacy-driven degradation to only {id}, and that the call is auto-approved. That is meaningful context beyond the structured fields.

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

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

Front-loads the core action and the return shape early, with the alternative tool and privacy caveat following. The nested field list is somewhat dense but each element earns its place by documenting the payload in the absence of an output schema.

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

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

With no output schema, the description carries the return contract fully, including the field list and the privacy fallback. Combined with annotation-covered safety and a 100%-documented schema, nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so both file_id and reason are fully documented in the schema. The description repeats the id source at best and adds no new parameter syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fetch metadata for a single Drive file by id') and enumerates the fields returned. It is clearly distinguishable from siblings like drive_get_file_content and drive_list_files, which are named 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?

Explicitly routes the agent to drive_get_file_content for reading file content and ties the id to drive_list_files/drive_list_folder. It gives clear context but no explicit when-not-to-use beyond the content-read alternative.

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 safe read-only profile, but the description adds much more: per-file-type return formats (Doc/Slides as plain text, Sheet as Markdown table, PDF/Office as extracted text, zip as entry list, images as placeholder), a 'truncated' flag, and possible redaction by privacy settings. This is exactly the extra context the annotations cannot carry.

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

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

Purpose is front-loaded in the first sentence, and the following sentences carry real information. The file-type enumeration is long but earns its place because there is no output schema defining the return shape; only slight run-on density 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?

With no output schema, the description fully documents the return object ({file_id, revision_id, modified_time, content} plus 'truncated'), the redaction caveat, and the approval requirement. Nothing an agent needs 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?

Schema description coverage is 100%, and each parameter (file_id, revision_id, reason) is already well documented in the schema. The description restates file_id/revision_id but adds no syntax or format detail beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Fetch the content of one earlier saved version of a Drive file, by file id and revision id') and clearly distinguishes itself from drive_get_file_content and drive_list_revisions. An agent can immediately tell what this returns and how it differs from its closest 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?

Gives explicit routing guidance: to compare against the current version, read the newest revision via drive_list_revisions with this tool rather than mixing in drive_get_file_content's different format. It names the alternative and the condition that selects it, and flags 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 already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral context beyond annotations: pagination behavior (reads across pages, capped at 1000, default 20), result ordering follows the Drive API query order, fields may be redacted by privacy settings, and it is 'Auto-approved'. It stops short of describing rate limits or failure modes, so it is strong but not exhaustive.

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

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

Purpose is front-loaded and the routing sentence is tight, but the mid-sentence enumeration of twelve return fields is dense and partly duplicates the informative clauses around it. Still, every sentence carries content, so it is efficient if slightly over-packed.

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

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

There is no output schema, so the description carries the full burden of describing the return value — and it does so thoroughly, enumerating the field set, the page/cap behavior, ordering, and privacy redaction. An agent has everything needed to call and interpret results 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 all three parameters are already documented in the schema. The description restates the max_results default/cap and the q-syntax nature of query rather than adding new meaning. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Search Google Drive and return matching file metadata') and explicitly distinguishes itself from siblings by naming drive_list_folder and drive_get_file_metadata with the conditions that select them. An agent can tell it apart 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?

Names two alternatives and the exact condition for each: drive_list_folder for one folder's children, drive_get_file_metadata when the file id is already known. Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes beyond them by disclosing pagination behavior ('read across pages'), the trashed-file exclusion, default and cap values, and ordering semantics ('in the order the Drive API gives'), which are real behavioral traits an agent needs.

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

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

Three sentences, front-loaded with the core purpose, then return shape, then the sibling alternative. Efficient overall, though the max_results default/cap sentence repeats what the schema already states and 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 read-only list tool with no output schema, the description supplies the missing return-shape information ('same shape drive_list_files returns') plus pagination, ordering, and filtering behavior. Nothing an agent needs to call it correctly is absent.

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

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

Schema coverage is 100%, so folder_id, reason, and max_results are all documented in the schema already. The description's restatement of the max_results default/cap and page-reading behavior largely duplicates the schema text, adding little new meaning. 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 ('List the direct children of a Drive folder by id') and explicitly distinguishes itself from its closest sibling by contrasting browsing one folder against searching by name/content. An agent can route between drive_list_folder and drive_list_files 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?

Names the alternative (drive_list_files) and the condition that selects it ('to search by name or content instead of browsing one folder'), plus the 'Auto-approved' note signalling no approval prompt is needed. Both when-to-use and when-to-use-the-other are covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: return shape, cross-page reads, the caveat that Google merges frequent edits and won't say which cell or paragraph changed, and that privacy settings can reduce entries to {id, before_cutoff}. These are non-obvious behavioral traits an agent needs.

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

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

Front-loaded with purpose then return shape, caveats, and alternatives, with every sentence carrying information. 'newest first' is stated twice and the trailing 'Auto-approved.' is slightly tacked on, but overall the density is appropriate for the complexity.

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, so the description carries the full burden of describing the return value and it does so completely, including the reduced-metadata edge case and pagination. Nothing needed to call or interpret the tool 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 100%, so the baseline is 3; the description adds meaning by explaining that the before_cutoff entry is returned in addition to max_results and that the cap leaves older versions out. It doesn't add syntax detail for modified_after beyond what the schema already documents.

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