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

Annotations only flag it as non-read-only and closed-world; the description adds real behavior: the Google path is asynchronous ('returns at once', approval happens in the browser, next call works), key-issuing apps need an out-of-band key stored via a terminal command, and it issues the guardrail 'Never ask the user for a key in the chat.' That is substantial context 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-loaded with the core action, then conditional behavior, then the sibling pointer and the guardrail. Every sentence carries distinct information; nothing is redundant filler.

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

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

For a one-parameter connect tool with no output schema, it covers the required prerequisites, the asynchronous return behavior for Google, and the follow-up verification path via `connection_status`. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% but the schema itself only says 'The app to connect' for a 6-value enum. The description adds per-value semantics by distinguishing key-issuing apps (stripe/linear/github/etc.) from Google's OAuth flow, which materially changes what happens after the call.

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 ('Connect one app this server uses') and immediately differentiates itself from the sibling `connection_status`, which is a status-read rather than a connect action. An agent can tell its function apart from the many *_create 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?

It explicitly routes the 'which apps are connected' intent to `connection_status` and gives distinct usage flows for key-issuing apps vs Google (own OAuth client must be set first). It does not state explicit when-not conditions beyond that, 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 already declare readOnlyHint=true and openWorldHint=false, so safety is covered by structured data. 'Changes nothing' restates the readOnly hint rather than adding new behavior; the only incremental value is noting that connect instructions are returned for unconnected apps.

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

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

A single tight sentence that front-loads the primary purpose and appends the secondary benefit with no filler.

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

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

For a no-param, read-only status tool with no output schema, the description covers both what is inspected and the shape of the useful payload (connect guidance). Return format details are absent but minimal given the tool's simplicity.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly implies no input is needed.

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

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

States a specific verb ('See') and resource ('which apps this server is connected to'), and adds the secondary payload of connect instructions for missing apps. This distinguishes it from the sibling 'connect' tool, which performs the connection rather than reporting status.

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

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

The phrase 'how to connect each one that is not' implies this tool is the discovery step before using 'connect', but the sibling is never named and there is no explicit when-to-use/when-not statement. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the description need only add context, and it adds none. It omits that this kicks off an asynchronous crawl job (a firecrawl_crawl_status sibling exists for polling), that pages/credits are consumed, and that a limit defaults to 10000.

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

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

A single front-loaded sentence with zero filler. It is efficient, though its brevity is partly under-specification rather than true economy.

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

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

For a 19-parameter, open-world, non-read-only crawl tool with no output schema, the description is far too thin. It says nothing about asynchronous job behavior, polling via crawl_status, scope controls (allowSubdomains, includePaths), or cost, all of which an agent needs 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 the 19 parameters are fully documented in the schema. The description contributes no additional parameter meaning, which is the baseline-3 case when the schema carries the load.

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: 'recursively crawl a website and scrape each discovered page.' The word 'recursively' and 'each discovered page' implicitly distinguish it from the single-page firecrawl_scrape sibling, but no sibling is 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?

Provides no when-to-use guidance, no conditions selecting it over firecrawl_scrape, firecrawl_map, or firecrawl_extract, and no prerequisites. The agent must infer usage purely from the verb.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, covering the safety profile. The description adds that it returns both status and results (not just status), which is useful context, but it omits polling guidance, rate limits, and result format 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?

A single front-loaded sentence with zero wasted words. It is appropriately sized for the simplicity of the tool.

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

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

For a simple read-only status tool with rich annotations and no output schema, the description is minimally adequate. It does not explain the async/polling nature of crawl jobs or what 'results' entail, leaving clear gaps for an agent that may need to know whether to call repeatedly.

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 single parameter 'id' is fully documented in the schema. The description adds no parameter-specific meaning beyond what the schema provides, which is the baseline for high coverage.

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

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

States a specific verb (Get) and resource (status and results of a crawl job), which clearly distinguishes it from the sibling firecrawl_crawl that likely starts a crawl. However, it does not explicitly name the alternative or state the relationship, so it falls short of a 5.

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

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

The description only says what the tool does; it gives no guidance on when to use it versus alternatives, no prerequisites, and no mention of polling behavior. Implied usage is weak because no context is provided about the crawl lifecycle.

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 (a mutation) and openWorldHint=true. The description adds only 'returns details of the event' and omits meaningful behavioral context for a mutation tool of this complexity: guest notifications, the sendUpdates/conferenceDataVersion/supportsAttachments side-effect flags, permission requirements, and attendee-invitation behavior are all undisclosed.

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

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

A single tight sentence with the action front-loaded and no filler. It is efficient, though the trailing return-value clause could arguably be dropped since it is the only content beyond the verb.

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 brief note about returned details is helpful, but for a mutation tool with 7 parameters and rich side-effect potential (invitations, notifications, conference generation) the description is thin. It is minimally adequate rather than 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 input schema fully documents all 7 parameters including sendUpdates, conferenceDataVersion, and maxAttendees. Per the rubric, that establishes a baseline of 3; the description adds nothing beyond the schema.

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

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

States a specific verb and resource ('Create a calendar event'), which clearly distinguishes it from the sibling gcalendar_events_list. It does not, however, differentiate itself from similar write operations or mention scope (which calendar), so it falls short of a 5.

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

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

The description gives no when-to-use context, prerequisites, or alternatives. An agent must infer that this is the creation counterpart to gcalendar_events_list without any explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that — no pagination behavior, no sync-token semantics, no note that results are scoped to a single calendar. It contributes no behavioral context of its own.

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

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

One short sentence with zero waste, and the action is front-loaded. But the brevity is under-specification rather than disciplined conciseness — it omits any usable context an agent would want for a 18-parameter list tool.

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

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

For a high-complexity tool with 18 parameters, no output schema, and paging/sync behavior, a single sentence is insufficient. The rich schema mitigates some of this, but the description supplies no operational framing (single-calendar scope, pagination, recurring-event expansion) that an agent needs 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% across all 18 parameters, so the schema carries full semantic burden (time bounds, orderBy constraints, syncToken exclusions, etc.). The description adds no parameter meaning whatsoever, 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 (List) and resource (events) plus a scope qualifier ('matching a given search filter'). However, 'search filter' is vague against an 18-parameter schema and the description offers no differentiation from the sibling gcalendar_events_insert or any hint of what the tool actually filters on.

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

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

No guidance on when to use this versus alternatives, no mention of prerequisites (calendarId required, calendarList.list to discover IDs), and no exclusions. The single sentence gives only the bare action.

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 mutation and open-world profile (readOnlyHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely useful behavior beyond that: Google itself parses the time and title, meaning the caller does not control field extraction and results may be approximate. It does not mention what happens on ambiguous text or what is returned, so it falls short of a 5.

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

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

Two tight sentences: the capability and example come first, the sibling routing second. Every clause carries load and nothing is repeated from the schema.

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

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

For a create tool with full schema coverage and no output schema, the description covers input semantics and tool selection well. The one gap is that it never indicates what the call yields (e.g., created event identifier), which an agent creating an event would likely need for follow-up calls.

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 earns one extra point by supplying a concrete example of the free-text format for the required 'text' parameter, which the schema only describes as 'the text describing the event'. calendarId and sendUpdates are left entirely to the schema, which is acceptable given full coverage.

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

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

States a specific verb and resource (create an event) and specifies the input mode (plain-text description), which makes it immediately separable from gcalendar_events_insert. The inline example makes the intended input shape concrete rather than abstract.

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 tool when you have free text, and use events_insert when the fields are already known. This names the alternative sibling and the condition that selects it, leaving nothing 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 readOnlyHint=false and openWorldHint=true, so the description carries the behavioral load and does well: it discloses the critical constraint that only the title is honoured and the document is created empty. It also notes the documentId is returned, which matters with no output schema. It stops short of noting auth/permission or quota 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 short clauses, zero padding, and the most important constraint (empty document, title-only) is front-loaded before the follow-up instructions. 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 compensates by mentioning the returned documentId and the batch_update follow-up, which is what an agent needs to chain calls. For a single-param mutation tool with annotations covering the safety profile, this is nearly complete; only auth/error behavior is absent.

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

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

Schema description coverage is 100% and the title field already states it is the only honoured field, so the description largely restates structured data. Baseline 3 applies; the emphasis on the empty-document effect is useful but not new information beyond the schema.

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

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

States a specific verb (create) and resource (document), and immediately disambiguates the scope: it produces a blank/empty document, not a content-bearing one. This is a distinct action an agent can tell apart from content-writing operations. The mention of documents_batch_update further fixes its place in the workflow.

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

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

Provides clear sequencing guidance: to add content, create first and then call documents_batch_update with the returned documentId. It does not state explicit exclusions or alternatives (e.g., when to use a copy/template flow instead), 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=true and idempotentHint=true, so safety is covered structurally. The description adds a genuinely non-obvious behavioral default: the default response covers only the first tab, which would silently truncate output for multi-tab documents. It does not mention auth scopes, payload size, or rate limits, so it is not fully exhaustive.

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

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

Three tight sentences, front-loaded with the purpose, then invocation details. It loses a point because the documentId URL-parsing sentence exactly duplicates the schema description and earns nothing new.

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 get with no output schema, the description covers what the operation does and the one behavioral trap (single-tab default) that would cause an agent to return incomplete content. Nothing further is required 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 the schema already documents all three parameters, including the tabs/body return-shape distinction for includeTabsContent. The description's documentId explanation is a verbatim restatement of the schema and its tab note largely duplicates the schema text, 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 ('Read') and resource ('a document's full structural content'), which is enough to separate it from gdrive_files_export, gsheets_spreadsheets_values_get and granola_notes_get. No ambiguity about what is fetched.

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

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

The sentence about passing include_tabs_content=true for multi-tab documents is conditional guidance on invocation, which is useful. However, there is no guidance on when to choose this tool over sibling read tools (gdrive_files_export, gsheets values get), or any stated prerequisites beyond the ID format.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true. The description adds no behavioral context beyond repeating the required 'fields' parameter, which is already documented in the schema. No mention of pagination behavior, rate limits, or auth requirements.

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

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

Two sentences, zero waste, with the required parameter front-loaded. Efficient and direct, though the example could be more complete.

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 description covers the mandatory parameter but neglects the other optional parameters (pageSize, pageToken, includeDeleted, startModifiedTime) that could affect usage. For a list tool with no output schema and rich schema documentation, it's adequate but incomplete.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters including the 'fields' requirement. The description repeats the 'fields' requirement, adding no syntax or format details beyond what the schema provides, which is the baseline for high schema coverage.

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

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

The description clearly states the verb 'List' and resource 'comments' scoped to a file. It doesn't explicitly distinguish from siblings, but the 'file's comments' scope is specific enough that the agent can identify it as the Drive comments-list tool.

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

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

No guidance on when to use this tool vs alternatives like gdrive_files_list or other comment-related operations. The description assumes the agent already knows it needs comments and just needs the fields parameter.

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 openWorldHint=true, so the write/non-safe nature is covered structurally. The description adds 'patch semantics' and the inheritance rule for omitted parents, but says nothing about the copy's sharing/permission behavior, comment copying, or quota effects.

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

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

Two sentences, zero filler, and the core action plus the common invocation pattern are front-loaded. Nothing here could be trimmed without losing meaning.

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

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

With 9 parameters all documented in the schema and no output schema, the description covers the basics of what the tool does. However, it omits the behavioral context an agent needs for a mutation tool: whether the source is modified, what the response contains, and permission/quota implications.

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's note about name/parents largely restates what the `file` parameter description in the schema already says, adding no new syntax or format detail.

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

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

States a specific verb and resource: 'Create a copy of a file', which is plainly distinguishable from the sibling gdrive_files_create. It does not explicitly name or contrast the sibling, so it stops short of a 5.

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

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

The sentence 'Typically send a new `name` and optionally `parents`' gives practical guidance on the common call shape, but there is no when-to-use/when-not-to-use framing, no prerequisite permissions, and no routing against alternatives like gdrive_files_create.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true, a minimal profile for a mutation tool. The description adds one genuinely valuable behavioral fact – concurrent writes on the same file are unsupported – but it does not disclose notification-email side effects, the ownership-transfer side effect, or permission-scope requirements, so it only partly fulfills the disclosure burden.

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 followed by the constraint-critical facts. Slight redundancy with the schema's own enum listings keeps it from being maximally efficient.

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

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

For an 8-parameter mutation with no output schema, the description covers the core grant semantics and one concurrency caveat but says nothing about what the call returns (the created Permission resource) or about the high-impact optional flags that live only in the schema. It is usable but not fully self-sufficient.

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 repeats the type and role enums and the emailAddress rule, all of which the schema already documents verbatim, and it adds no meaning for the other six parameters (transferOwnership, sendNotificationEmail, useDomainAdminAccess, etc.).

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 permission for a file or shared drive') and no sibling tool overlaps with permission management, so ambiguity is nil. The follow-on sentences make clear it is about granting a role on a Drive item rather than creating the item 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?

Usage is implied by the create semantics and the field-combination rules (emailAddress for user/group, role/type pairings), but there is no explicit statement of when to use this versus a sibling or what prerequisites/auth are needed. Adequate but leaves the agent to infer 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 already declare readOnlyHint=false and openWorldHint=true, so the agent knows this is a mutating external operation. The description adds the conditional requirement between content and action, but that same rule is already stated in the content field's schema description, so it contributes little beyond structured data. Permissions/scopes and response behavior are not mentioned.

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

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

Two short sentences with zero waste. The core purpose is front-loaded, followed immediately by the payload options, and no sentence is redundant.

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

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

For a simple create tool with a fully documented schema and no output schema, the description covers what is needed to invoke it correctly. Minor gaps remain around required scopes and confirmation of a returned reply object, but nothing blocking.

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

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

Schema description coverage is 100%, so all three parameters and the nested reply object are already documented with descriptions, including the enum values resolve/reopen and the content requirement. The description restates the content/action relationship rather than adding new semantics, 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: 'Create a reply to a comment.' An agent can tell this apart from unrelated siblings like gdrive_comments_list or gdrive_permissions_create, though the description does not explicitly distinguish itself from any near-neighbor tool.

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

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

Usage is implied by the guidance to 'Send `content`, or an `action` of `resolve` or `reopen`,' which tells the agent what to supply but not when to prefer this tool over alternatives or what preconditions exist (e.g., the comment must already exist in the file). No explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is fully covered structurally. The description adds the 'newest first' ordering trait, but says nothing about pagination behavior, result caps, or rate limits that the annotations don't cover.

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

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

Two short sentences with zero filler; the ordering behavior is front-loaded and the filtering options follow compactly. Every clause earns its place.

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

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

For a 9-parameter read tool with full schema coverage, no output schema, and annotations covering safety, the description supplies the key behavioral trait (ordering) and a map of the main filters. Pagination via page/perPage is only in the schema, a minor omission rather than a blocking one.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in the schema (including defaults for page/perPage and ISO 8601 format for since/until). The description only restates sha/path/since/until usage without adding format or edge-case detail, 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+resource ('List commits') plus an ordering guarantee ('newest first'), which is more than the name alone conveys. There is no sibling commit-listing tool to differentiate against, so the lack of explicit contrast is not a gap here.

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

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

Explicitly tells the agent how to narrow results: `sha` for a branch, `path` for one file's history, `since`/`until` for a time window. This is clear usage guidance, though it never states when-not to use the tool or names an alternative tool for other commit-listing needs.

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 openWorldHint=true, so the write/non-read nature is covered structurally. The description adds nothing beyond that: it does not say the draft is not sent, whether creation is idempotent, or what auth is required, so the behavioral burden is largely unmet.

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

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

A single front-loaded sentence with no filler, which is well structured. It is arguably under-specified rather than bloated, but as a size/structure judgment it is tight and readable.

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 write tool with only minimal annotations and no output schema, the description should at least clarify that it saves rather than sends and hint at the returned draft. The rich input schema compensates for parameters, but the core behavioral distinction is left 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 the nested Message/Draft/EmailContent fields are richly documented (threadId rules, bodyHtml multipart behavior, in_reply_to threading). The description adds no parameter meaning at all, 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+resource ('Save an email draft') and destination (Gmail), which is enough to know it creates a draft rather than sending. However, it does not distinguish itself from the adjacent gmail_messages_send sibling, so an agent gets no explicit routing cue.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the alternative tool (gmail_messages_send) for actually delivering mail. The agent must infer that this only persists a draft.

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 openWorldHint=true, so the safety profile is partially covered. The description adds no behavioral traits beyond that, such as immediate sending, authentication requirements, irreversibility, or threading behavior; it essentially restates the tool name.

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

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

It is a single, front-loaded sentence with no wasted words. While it is sparse, the structure is efficient and the core action is stated first.

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 open-world annotations and no output schema, the description is incomplete. It does not clarify that the message is sent immediately rather than saved as a draft, nor does it describe return behavior or error handling, leaving important context gaps.

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

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

Schema description coverage is 100%, and the nested EmailContent fields are fully documented. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb (Send) and resource (email via Gmail API), which is clearer than a generic action. However, it does not differentiate from sibling tools like gmail_drafts_create or slack_chat_post_message, so it misses the top mark.

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 offers no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It simply states the action without any contextual routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered by structured data. The description adds nothing beyond that — no note on pagination behavior, result ordering, or the fact that a full mailbox scan may be needed without filters.

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

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

A single short sentence with no filler and the key information front-loaded. It is efficient, though the extreme brevity shades into under-specification rather than pure conciseness.

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

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

For a 6-parameter read tool with no output schema, the description is minimally viable: the schema covers all inputs, but the description omits pagination semantics and what a thread result contains. Nothing is misleading, but an agent gets no help beyond the structured fields.

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 (q, userId, labelIds, pageToken, maxResults, includeSpamTrash) is already documented in the schema. The description contributes no additional meaning, which is the baseline 3 case 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 ('List') and resource ('Gmail threads'), which is unambiguous and distinguishable from write-oriented siblings like gmail_messages_send and gmail_drafts_create. It stops short of scope details (e.g. mailbox-wide vs. label-filtered), so it is clear but not maximally informative.

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

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

No guidance on when to use this tool versus alternatives, no mention of prerequisites or the conditions under which a caller should prefer it. The sibling set contains other Gmail operations but the description offers no routing signal.

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 openWorldHint, so the safety profile is covered. The description adds materially useful behavior beyond that: the 413 TRANSCRIPT_TOO_LARGE failure mode and the fallback path to notes_transcript_get, which an agent cannot infer from structured fields.

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

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

Three tight sentences, front-loaded with the core purpose and followed by the opt-in parameter and its failure path. No filler and every sentence carries distinct information.

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

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

With no output schema, the description carries the return-value burden, and it does so by enumerating the returned fields (summary, attendees, calendar event, folders). Combined with the error-handling note, nothing needed to call or interpret this read 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 description coverage is 100%, so both noteId (format constraints) and include are already fully documented in the schema, making 3 the baseline. The description's 'Pass include=transcript' largely restates the schema description and its TRANSCRIPT_TOO_LARGE note, adding little syntax or format detail beyond it.

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 ('Read one meeting note') and immediately distinguishes scope from the sibling granola_notes_list by emphasizing the singular note. It enumerates exactly what comes back (AI summary, attendees, calendar event, folders), so an agent knows the payload 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 conditional guidance for the transcript case ('Pass include=transcript') and routes to the alternative tool (notes_transcript_get) when the transcript is too large. It does not explicitly contrast with granola_notes_list, which is left implicit via 'one meeting note'.

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 provide readOnlyHint=false and openWorldHint=true, indicating a mutating, external operation. The description adds nothing beyond this – it doesn't disclose how appended data interacts with existing tables, whether headers are auto-detected, or rate-limit/permission requirements. For a mutation tool, this is a significant gap.

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

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

Single, front-loaded sentence that wastes no words. However, the extreme brevity contributes to gaps elsewhere.

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

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

Given the tool's complexity (8 parameters, nested value types, mutation behavior), the description is critically underspecified. It omits key behavioral details like how the append range is determined, interaction with existing data, and available options (insertDataOption, valueInputOption). No output schema exists to compensate.

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 parameters are fully documented in the schema. The description adds no parameter-level detail beyond what's already provided. Baseline 3 is appropriate.

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

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

The description states a specific verb (appends) and resource (values to a spreadsheet), which is clear but does not differentiate from the sibling gsheets_spreadsheets_values_update or clarify the 'logical table' append behavior. It's clear but lacks sibling differentiation within the gsheets tool family.

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

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

No guidance on when to use this tool vs alternatives like gsheets_spreadsheets_values_update, and no mention of required preconditions or idempotency considerations. The description is silent on usage context.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the mutation/external-scope profile is covered. The description adds genuinely useful behavior: Linear rejects names and only accepts UUIDs resolved via teams_list/users_list/workflow_states_list, and parent_id turns this into a sub-issue creation. It stops short of noting side effects like notifications or returned identity.

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 the required fields, followed by the ID-resolution constraint and the sub-issue tip. No filler, though the UUID guidance partially duplicates the schema text.

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

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

For a create tool whose one parameter is a deeply nested object fully documented by the schema, plus annotations covering the safety profile, the description covers the essentials an agent needs. It lacks any mention of what creation returns, which is a minor gap given there is no output schema.

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

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

Schema description coverage is 100%, so the schema already documents every field including the resolver-tool hints and the sub-issue semantics. The description's parameter notes (team_id/title required, everything else optional) largely restate the schema rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create an issue'), which is instantly distinguishable from the list-oriented sibling linear_issues_list. It does not explicitly name a sibling it is not, so it falls short of a 5, but the purpose is unambiguous.

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

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

The description gives practical invocation guidance (required vs optional fields, which resolver tools supply UUIDs, how to make a sub-issue) but never states when to reach for this tool versus alternatives such as linear_issues_list, nor any exclusion or prerequisite conditions. Usage is implied rather than framed.

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 openWorldHint, so the safety profile is covered by structured data. The description's contribution is the AND-combination rule for filters, but that same rule is already documented in the schema's filter field, so added value is minimal beyond confirming the semantics.

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

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

Three short sentences, zero filler, with the core purpose front-loaded and the practical example last. Every sentence earns its place.

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

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

For a read-only list tool with a fully documented filter schema and no output schema, the description covers purpose, filter semantics, and a usage pattern. Slightly short on pagination/ordering behavior, though that is documented in the schema's variables object.

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 nested comparators are fully documented, so the schema does the heavy lifting. The description's filter guidance (AND combination, team.key/state.type paths) largely repeats what the schema already states, making 3 the appropriate baseline.

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

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

States a specific verb ('List') and resource ('issues') with scope note 'optionally filtered'. It distinguishes itself from the sibling write tool linear_issue_create implicitly, but never names a sibling or explicitly rule out other Linear tools.

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

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

Gives a concrete when-to-use example: 'To find a team's open work, filter on team.key and state.type.' It provides clear positive usage context but no when-not guidance or named alternative for other listing scenarios.

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

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

The annotations already declare readOnlyHint=false and openWorldHint=true, so the agent knows this is a mutating, externally visible operation. The description adds required-input and dependency information, but does not disclose side effects, authentication needs, rate limits, or what the creation returns.

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

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

The description is two tight sentences with no wasted words. The core action is front-loaded, and the required-field note follows immediately.

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 project-creation tool with full schema descriptions and annotations covering mutability, the description gives enough to call the tool correctly: the required fields and where to obtain team UUIDs. It is slightly thin on optional-field behavior and return expectations, though the schema covers those details.

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 adds meaningful guidance beyond the schema by naming `teams_list` as the source for team UUIDs and reiterating which fields are required.

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

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

The description states a specific verb and resource: 'Create a project.' This clearly identifies the operation, but it does not explicitly distinguish this tool from sibling tools such as linear_project_update_create or linear_projects_list.

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

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

It provides clear prerequisite context: `name` and at least one team UUID are required, and it names `teams_list` as the source for team UUIDs. It does not, however, state when not to use this tool or contrast it with alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description adds useful return-scope context (content, milestones, members) but does not disclose auth requirements, rate limits, or error behavior beyond what annotations provide.

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

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

Two tight sentences, front-loaded with the core action and return scope followed by the accepted identifier forms. Every phrase contributes information and there is no boilerplate.

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

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

For a single-parameter, read-only tool with full schema coverage and clear annotations, the description leaves little missing. It names the main returned sub-resources but does not clarify edge cases like not-found behavior or what 'content' includes in detail.

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 description's parameter note ('Accepts the project's UUID or the slug from its URL') merely repeats the schema description for 'id' without adding format examples, ambiguity resolution, or lookup behavior. Baseline 3 is appropriate when the schema already documents the sole parameter.

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

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

States a specific verb and resource ('Get one project') and adds scope ('with its content, milestones and members'). This distinguishes it implicitly from list tools like linear_projects_list, but it never explicitly names an alternative or sibling, so it falls short of the highest clarity tier.

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

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

The description gives no when-to-use guidance, no prerequisites, and no mention of alternatives such as linear_projects_list or other project endpoints. It only says what the tool fetches, not when an agent should choose it.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, so the mutation/create nature is covered. The description usefully discloses the return value (a hosted payment URL), which matters since no output schema exists, but it omits side effects, session lifecycle, or what happens on expiry/cancellation.

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

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

Two tight sentences: the action/outcome is front-loaded and the key parameters follow. Nothing is redundant or 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?

For a 13-parameter, high-complexity tool the description is thin, though the rich schema (100% coverage) carries the parameter burden and the hosted-URL outcome is stated. It is sufficient to call correctly but leaves session behavior and the payment-vs-setup distinction under-explained.

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 13 parameters are already documented, and the description only echoes line_items and mode. It adds no syntax or constraints beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb+resource ('Create a Checkout Session') and even names the outcome ('get a hosted payment URL'), so the agent immediately understands what it produces. It does not, however, distinguish this tool from neighboring Stripe creation tools such as stripe_invoices_create or stripe_subscriptions_list.

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

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

It gives concrete invocation guidance ('Pass line_items with price IDs and quantities', mode='payment' vs mode='subscription'), which implies usage. But it never says when to prefer this over alternatives like stripe_invoices_create, nor any prerequisites such as existing customers or prices.

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 openWorldHint, so the safety profile is covered. The description adds a genuine behavioral caveat (no payment_status filter, must inspect results), but that partially overlaps with the schema's own note that 'complete' means finished, not necessarily paid.

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

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

Two short sentences with zero waste; the core purpose is front-loaded and the caveat follows immediately. Nothing could be cut without losing meaning.

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

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

For a read-only paginated list tool with a fully documented schema and annotations, the essentials are present. However, with no output schema, the description does not indicate the shape of returned sessions or pagination behavior, leaving a visible gap for an agent planning to scan results for paid sessions.

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

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

Schema description coverage is 100% across all 9 parameters, including timestamp units and pagination cursors, so the schema does the heavy lifting. The description adds no parameter-level detail, making the baseline 3 appropriate.

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

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

States a specific verb and resource ("List checkout sessions"), which is unambiguous against the sibling stripe_customers_list. It does not explicitly name an alternative or scope, so it stops short of the sibling-differentiation a 5 would require.

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

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

The second sentence implies a usage pattern — when you want paid sessions, you must read the results because there is no payment_status filter. That is useful implied guidance, but there is no explicit when-to-use/when-not-to-use framing or named alternative tool.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true, so the description must carry the rest. It says nothing about idempotency, whether the call is reversible, what permissions or API key scope are needed, or that a customer ID is returned and needed downstream (e.g., for checkout sessions or invoices).

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

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

A single front-loaded sentence with zero waste. It is efficient, though its brevity reflects under-specification rather than disciplined conciseness, so it does not reach a 5.

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

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

For a 10-parameter mutation with no output schema and only two coarse annotations, the description omits anything an agent needs beyond the schema: no return value, no error/idempotency behavior, no note that this is the prerequisite step for invoices, subscriptions, or checkout sessions.

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 (balance units, taxExempt enum values, paymentMethod create-only behavior) is already documented in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a customer'), so the operation is unambiguous. However, it does nothing to distinguish this from the sibling linear_customer_create or to indicate which platform's customer model is being created, which a 5 would require.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as stripe_customers_retrieve or linear_customer_create. The agent must infer that this is the Stripe-side entry point for creating a customer record.

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 disclose mutation (readOnlyHint=false) and open-world reach, so the safety profile is covered. The description usefully adds lifecycle behavior — that a line without `invoice` defers to the customer's next subscription invoice — which is non-obvious and not captured by annotations.

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

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

Three short sentences, zero filler, with the core action front-loaded and the deferred-invoice caveat last. 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 15-parameter mutation tool with full schema coverage, annotations for the mutation profile, and no output schema, the description covers purpose, the two pricing paths, and the missing-invoice behavior. The required `customer` parameter is left to the schema, a minor gap.

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

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

Schema coverage is 100% and the schema already documents all 15 parameters in depth (units, formats, limits). The description's `pricing.price` vs `amount` note restates what the schema says, adding little beyond it, 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?

"Add a line to an invoice" gives a specific verb and resource that clearly maps to creating a Stripe invoice item, and the pricing/amount guidance sharpens it. It does not explicitly name or rule out sibling tools such as stripe_invoices_create, so it stops short of full sibling differentiation.

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

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

It states two concrete ways to supply the line's value (name an existing price via `pricing.price`, or pass `amount` directly) and explains the conditional behavior when `invoice` is omitted. It gives clear operating context but no explicit when-to-use-this-vs-an-alternative routing.

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

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

The readOnlyHint/idempotentHint/openWorldHint annotations already declare that this is a safe, non-mutating, idempotent read against external data, so the behavioral bar is lowered. The description adds one real behavioral fact not covered by annotations, the default sort order, but says nothing about default page size or pagination behavior beyond what the schema already carries.

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

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

Two short sentences with zero filler, and the ordering behavior is front-loaded immediately after the core verb-resource statement. Every clause carries information an agent would otherwise have to infer.

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

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

For an eight-parameter, zero-required list tool with 100% schema coverage and annotations that cover the safety profile, the description supplies the two things the schema cannot: ordering and the set of filterable dimensions. Pagination semantics are left to the schema, which is acceptable given the rich cursor descriptions, though a brief note would have closed the gap.

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

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

Schema description coverage is 100%, so the schema fully documents all eight parameters including timestamps, cursors, and enums, making 3 the baseline. The description names four of the filter dimensions but adds no semantics beyond the schema and omits the created-window and pagination parameters entirely.

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 (invoices) plus the sort order (most recently created first), which lets an agent distinguish it from the mutation siblings stripe_invoices_create and stripe_invoices_send without opening a schema. It does not explicitly name those alternatives, so it stops short of full sibling differentiation.

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

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

The second sentence enumerates the available filter dimensions (customer, subscription, status, collection method), which implies when to use the tool for narrowing a result set. It offers no explicit when-not guidance, no mention of pagination as a usage consideration, and no routing to sibling list tools.

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