Relaticle

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add behavioral substance — it does, disclosing that the output is counts and summed pipeline amount and that the date bounds apply to creation date specifically, which is a non-obvious filter semantic. It does not mention empty-group handling or result ordering.

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

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

A single front-loaded sentence that names the metrics and the grouping axis first, then the optional filter. Nothing here 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 an output schema present and full parameter documentation, the description needs only to frame what is computed and how filtering works, which it does. Only edge-case behavior (groups with zero opportunities, ordering, whether ungrouped totals are available) is left unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3; both date parameters are already documented as YYYY-MM-DD creation-date bounds and group_by is documented in the schema. The description's 'creation-date bounds' phrasing reinforces the filter semantics but adds little beyond what the schema already says.

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 (aggregate) plus the resource, the two metrics produced (opportunity counts and pipeline amount), and the grouping dimensions. It is clearly distinguishable in kind from list-opportunities-tool, though 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?

The word 'aggregate' plus 'by stage or company' implies this is the roll-up path rather than the row-listing path, but there is no explicit 'use this instead of list-opportunities-tool when you want totals' statement and no exclusions. Usage is inferable, not stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds genuine context by clarifying the operation is purely additive ('without removing existing ones'), but says nothing about failure behavior — e.g., whether an invalid ID aborts the whole call, or whether repeat calls duplicate links.

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

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

Two short sentences, zero filler, with the operation and its non-destructive scope front-loaded. Nothing is repeated from the title or schema.

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

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

With an output schema present and all parameters documented, the definition is callable as-is. What is missing is behavior under partial failure or mixed entity-type batches, which matters for a multi-target relationship mutation, and any pointer to the detach counterpart for reversing the change.

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 each parameter's meaning is already documented in the schema. The description only restates the three target entity categories and adds no extra semantics, such as whether all three lists can be supplied in one call or how duplicates are handled — 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 (attach) and resource (note) plus the three supported target entity types (companies, people, opportunities). The clause 'Adds links without removing existing ones' implicitly separates it from the sibling detach-note-from-entities-tool, though the alternative is never named directly.

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

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

Usage is implied: attach instead of detach, and additive rather than replacing. But there is no explicit 'use this when...' guidance, no mention of detach-note-from-entities-tool or update-note-tool as alternatives, and no stated preconditions (e.g., the note must already exist, IDs must be valid).

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

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

Annotations already declare destructiveHint=false and idempotentHint=true, so the additive semantics is partly covered; the description's restatement adds mild confirmation rather than new information. It says nothing about batch failure behavior (e.g. whether an invalid ID aborts the whole attach), permission requirements, or the effect on entities not listed. For a mutation tool with annotation coverage, a 3 fits.

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

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

Two short sentences, zero waste, with the resource/scope stated before the additive-behavior caveat. Nothing redundant and nothing buried.

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

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

An output schema exists and all five parameters are documented, so the definition is nearly complete for a straightforward relationship-creation tool with full annotations. The remaining gap is batch/error semantics when multiple IDs are supplied, which an agent may need before calling with arrays.

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 tells the agent which IDs go where, including a pointer to the whoami tool for user IDs. The description merely re-lists the four entity types without adding format, limits, or array-size guidance, so the baseline 3 applies.

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

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

Specific verb+resource: 'Attach a task to companies, people, opportunities, or assign to users,' which maps cleanly onto the four relationship parameters. It is implicitly distinguishable from detach-task-from-entities-tool and attach-note-to-entities-tool, but it never names a sibling explicitly, so it stops short of the top 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?

'Adds links without removing existing ones' gives a useful hint about when this is appropriate versus an update/replace operation, but there is no explicit when-to-use, when-not-to-use, or routing to detach-task-from-entities-tool. Usage has to be inferred 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 flag destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the description's job is to add context, and it does: the state gate on 'queued' explains when the tool will fail. It does not say what happens on a rejected cancellation (error vs silent no-op), which is the remaining behavioral 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?

Two sentences, both earning their place: the action/outcome comes first, then the eligibility constraint. No restatement of the title or 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?

Output schema and annotations carry the return shape and safety profile, so the description only needs purpose plus the state prerequisite, both present. Slightly incomplete on post-condition behavior when cancellation is rejected.

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

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

With a single parameter at 100% schema description coverage, the schema already defines `id` fully; the description only reinforces scope ('one of the current user's queued emails') without adding format or sourcing detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (cancel) plus resource and scope (one of the current user's queued emails), and adds the outcome ('so it is never sent'), which separates it from send/reschedule/retry siblings by implication. It never names an alternative tool explicitly, 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?

Gives a clear precondition for use: the email's status must be 'queued', and 'once it is sending, it is too late'. That is real when-to-use guidance, but it does not point at reschedule-email-tool or retry-email-tool for the cases where cancellation is not applicable.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and the description does not contradict them. The description adds one piece of real behavioral context (unknown custom field codes will be rejected), but it omits duplicate-name behavior and confirmation of what is returned, so with annotations carrying the safety profile a 3 fits.

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, core action front-loaded, prerequisite second. Nothing is padded, though the second sentence duplicates schema guidance rather than adding to it.

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

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

For a mutating create tool with a nested-object parameter, the description is adequate but thin: output schema exists so return values need not be explained, but duplicate handling, required permissions, and how the tool relates to list/create siblings are missing.

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

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

Schema description coverage is 100%, so every parameter (including the nested custom_fields object and its field-code rules) is already documented in the schema. The description's mention of crm-schema merely restates what the custom_fields schema text 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 new company in the CRM"), which cleanly separates it from create_people_tool, create_opportunity_tool and the like by entity type. It adds only the CRM context beyond the name, but for a CRUD create tool that is enough to identify it.

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

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

It gives one real prerequisite — read the crm-schema resource to discover custom fields — which is actionable. It says nothing about when to prefer this over update-company-tool, or how to handle an existing company (dedupe path), so guidance is implied rather than complete.

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

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

Annotations already declare non-readOnly, non-destructive, non-idempotent, closed-world behavior, but the description adds real value by disclosing that no email is dispatched, that the draft surfaces in the Drafts folder of Relaticle, that signatures are auto-appended, and that raw HTML is escaped. It does not mention duplicate-draft behavior or any permission requirements, 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, no filler, and the most important fact for an agent's decision (nothing is sent) is placed immediately after the purpose statement. Each sentence carries distinct operational 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 an output schema present, return values need not be explained, and the description covers the mutation's real-world effect, content format, and signature default for an eight-parameter tool. What remains thin is the relationship to the update/send/delete draft siblings, which an agent must work out from names.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including the markdown/HTML-escape rule, the 255-character subject limit, and the signature default. The description's body-format and signature notes largely restate the schema, which is the expected baseline-3 case rather than added 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 ('Save an email draft') plus the scope ('one of the current user's mailboxes'), and the phrase 'Nothing is sent' implicitly separates it from send-email-tool and send-email-draft-tool. It stops short of naming those siblings or the update/delete draft tools, so an agent still has to infer the boundary from tool names alone.

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

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

'Nothing is sent: the user reviews and sends it from Drafts' implies when this is preferable to a send tool, but the when-to-use is left implicit rather than stated as a condition ('use when the user wants to prepare but not send'). No prerequisites are called out in prose, though the schema field for connected_account_id points at the list email accounts tool.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds one behavioral fact — that unknown custom field codes are rejected — but that same warning is already repeated almost verbatim inside the custom_fields schema entry, so the incremental value is modest.

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

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

Two short sentences with the action front-loaded and the prerequisite second; there is no padding. Minor redundancy exists because the crm-schema instruction duplicates the schema's own warning, costing a perfect score.

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?

An output schema exists, so return values need no explanation, and the required title parameter is obvious. Still, for a five-parameter create tool with nested custom_fields and overlapping entity-linking capability, the description omits the create-vs-attach-vs-update decision, which is the main thing an agent could get wrong.

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 detailed guidance on custom_fields, so the baseline is 3. The description contributes nothing parameter-specific beyond echoing the schema's crm-schema instruction, and says nothing about how the three ID-array parameters interact with the dedicated attach tool.

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

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

The description gives a specific verb and resource ("Create a new note") scoped to the CRM, so the agent knows exactly what object is produced. It does not differentiate itself from siblings like update-note-tool or attach-note-to-entities-tool, leaving the boundary implicit.

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

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

It supplies one concrete prerequisite (read crm-schema before supplying custom fields), which is real guidance. However, it never states when to use this tool versus attach-note-to-entities-tool for linking people/companies/opportunities, nor how it relates to update-note-tool, so the main selection ambiguity is unresolved.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is known. The description adds a useful behavioral warning that unknown field codes are rejected, but that same warning is already in the schema's custom_fields description, so the added value beyond structured fields is modest.

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

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

Two short sentences with the core action front-loaded and the dependency second. No filler or repetition.

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

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

With an output schema present, annotations covering the write semantics, and full schema coverage, the description does not need to explain return values. It is nearly complete, though it could briefly state whether company/contact associations are validated or optional, since only name is required.

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

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

Schema description coverage is 100%, so all four parameters, including the nested custom_fields object and its field-code formatting rule, are fully documented in the schema. The description adds no syntax, defaults, or constraints beyond restating the schema dependency, so the baseline 3 applies.

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

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

The description gives a specific verb plus resource ("Create a new opportunity (deal)"), which distinguishes it by resource from siblings like create-company-tool and create-people-tool. It stops short of explicitly naming an alternative operation such as update-opportunity-tool, so it is clear but not maximally differentiated.

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

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

The second sentence gives a real prerequisite for the custom_fields path (read crm-schema first), which implies when that parameter matters. However, there is no guidance on when to use this versus update-opportunity-tool or how to handle existing deals, leaving the core when-to-use decision implicit.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, and the description adds essentially nothing beyond that: no statement about duplicate-person behavior, required field validation failures, or side effects. The one extra sentence about crm-schema duplicates the input schema's custom_fields warning verbatim in spirit.

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

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

Two short sentences, front-loaded with the action and resource, zero padding. It could arguably fold the schema hint into a single clause without loss, but there is no wasted sentence.

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?

Output schema exists, so return values need not be described, and the schema fully documents parameters. Still, for a non-idempotent create against a CRM with a companion update/delete and a likely duplicate-check workflow, the description says nothing about post-creation behavior or how to avoid creating duplicates.

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 custom_fields property already spells out the crm-schema prerequisite and exact-field-code requirement in detail. The description's mention of crm-schema restates that; it adds no semantics for name or company_id 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 and resource ('Create a new person (contact) in the CRM'), which distinguishes it from create-company-tool and create-opportunity-tool by entity type. It does not explicitly differentiate from update-people-tool or create-people-tool sibling semantics, but the verb carries most of the weight.

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 one concrete prerequisite: read the crm-schema resource to discover custom fields. However it gives no guidance on when to use this versus update-people-tool, nor on whether to check for an existing person first — even though the tool is explicitly non-idempotent, which makes that question material.

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 disclose that this is a non-read-only, non-idempotent, non-destructive, open-world creation operation. The description adds the custom-field schema prerequisite, but it does not explain permissions, side effects, or how linking interacts with existing people/company 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 two short sentences and front-loads the main action. The second sentence provides a practical prerequisite without unnecessary detail.

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

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

With a rich input schema, full parameter descriptions, annotations, and an output schema, the description covers the essential action and custom-field prerequisite. It is slightly incomplete regarding sibling-tool selection and linking strategy, but those gaps are partly covered by the schema and tool names.

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

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

Schema description coverage is 100%, so all parameters are already documented in the input schema. The description mentions only custom fields and repeats the crm-schema requirement already present in the schema; it adds little parameter meaning beyond that baseline.

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

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

The description states a specific verb and resource: create a new task in the CRM. It clearly distinguishes this from sibling tools such as list-tasks-tool, update-task-tool, delete-task-tool, and attach-task-to-entities-tool by naming the create action on the task entity.

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

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

It gives a useful prerequisite for custom_fields by directing the agent to the crm-schema resource. However, it does not explain when to use this tool versus attach-task-to-entities-tool or whether links should be provided at creation time versus attached afterward.

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 behavioral context beyond the readOnlyHint/destructiveHint/idempotentHint annotations: the URL is short-lived, the upload is capped at 10 MB, the file-type whitelist, and the fact that this tool only starts a workflow that must be completed by upload-file. It does not state the actual TTL or what error surfaces when the URL expires or the size cap is exceeded, 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?

Three sentences, front-loaded with the core action and constraints, then the follow-up step, then the alternative route. Nothing is wasted and the ordering matches how the agent needs the 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 one-parameter starter tool with an output schema and annotations present, the description supplies the key missing context: size limit, accepted types, URL lifetime, and the required downstream call. It leaves minor gaps around failure modes (expired URL, over-size file) but nothing an agent needs in order to invoke it correctly on the happy path.

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?

Only one parameter and schema coverage is 100% — the schema already documents that filename must include its extension and enumerates the allowed extensions. The description's extension list simply repeats that, adding no 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 — 'Get a short-lived signed URL to PUT a file body to' — and immediately distinguishes it from the sibling upload-file by contrasting the two-step flow with the direct source_url/base64 path. An agent can tell exactly which of the two upload tools this is.

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 in both directions: use this tool to obtain a PUT target, then call upload-file with the returned upload_id; but prefer upload-file directly with source_url or base64 'when you can.' That is a when-to-use / when-to-prefer-an-alternative statement, not an implication.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new information beyond that: the delete is a *soft* delete, meaning the record is likely retained/recoverable rather than purged, which materially changes how an agent should weigh the destructive hint. It stops short of saying whether related entities (opportunities, notes, tasks) are affected or what permissions are required.

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

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

One short sentence, front-loaded with the verb and resource, with the qualifier 'soft delete' placed where it will be read. 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?

An output schema exists so return values need no explanation, and a single documented parameter keeps the tool simple. However, for a destructive mutation the description omits cascade/side effects on attached records and any prerequisites or permission requirements, leaving real gaps for a high-consequence operation.

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

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

With a single parameter at 100% schema description coverage, the schema already fully documents 'id'. The description adds no format, source, or lookup guidance (e.g., how to obtain a company ID, whether it accepts an external ID). Baseline 3 applies 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 ('Delete') and resource ('a company from the CRM'), which cleanly distinguishes it from the many sibling delete tools (delete-people-tool, delete-note-tool, delete-opportunity-tool, etc.). It does not, however, contrast with update-company-tool or explain the scope of what 'delete' means for a company record.

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

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

There is no guidance on when to use this versus alternatives: no mention of when to prefer update-company-tool, no preconditions (does the company need to exist? must it be empty?), and no note about reversibility or restoration. The agent is left to infer usage entirely from the tool name.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the bar is lower; the description still adds genuine value by stating the deletion is permanent ('for good') and that attached files are removed too, which the annotations cannot convey. It stops short of saying what happens when the draft_id does not exist.

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

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

A single compact sentence with the destructive/permanent nature front-loaded, followed by the attachment caveat and the reassurance clause. 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?

An output schema exists and annotations cover the safety profile, so the description only needed to cover permanence and side effects, which it does. Only the missing-draft behavior (given idempotentHint=false) is left unaddressed.

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

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

Only one parameter and schema coverage is 100%, with the schema itself explaining how to obtain the draft_id. The description adds nothing about the parameter, 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 (delete) and resource (the current user's saved drafts) with scope and permanence. 'Nothing is sent' implicitly separates it from send-email-draft-tool, but the sibling is never named, so the differentiation is inferential rather than explicit.

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

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

No explicit when-to-use or when-not-to-use guidance, and it never contrasts with update-email-draft-tool or cancel-email-tool. The 'nothing is sent' clause only indirectly implies 'use this when you want removal, not delivery.'

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is defined. The description adds meaningful context by disclosing that this is a soft delete, which informs the agent about recoverability. However, it does not cover permissions, side effects on associations, or behavior when the ID is missing.

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

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

The description is a single, front-loaded sentence with no wasted words. It delivers the key operations and the soft-delete qualifier 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?

An output schema exists and annotations already cover the destructive nature, so the description does not need to explain return values. The soft-delete disclosure is important context for a deletion tool. It could be more complete by mentioning whether associations are removed or how recovery works, but it is largely sufficient for a simple delete operation.

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

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

Schema description coverage is 100% and the single parameter is documented as 'The note ID to delete.' The description adds no further parameter semantics, 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 and resource: 'Delete a note from the CRM'. It is clear what the tool does and which entity it operates on, though it does not explicitly differentiate itself from sibling delete or detach 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?

There is no guidance on when to use this tool versus alternatives such as detach-note-from-entities-tool or update-note-tool, nor any when-not conditions. Usage is only implied by the operation name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds the meaningful nuance that deletion is a soft delete, but omits whether it can be undone, whether attached notes/tasks/emails are cascade-detached, and what the response reports.

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, front-loaded with the action and resource, with the important "soft delete" qualifier attached rather than buried. 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?

Output schema and annotations cover the return shape and safety profile, and the parameter is documented. Still, for a destructive CRM operation the description should say what happens to linked records and whether the soft delete is reversible; those are the gaps an agent would actually need.

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?

Single required parameter with 100% schema description coverage, so the schema fully documents it. The description adds nothing about ID format or how to obtain a valid ID (e.g., via list-opportunities-tool), which is the baseline expectation when schema 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?

States a specific verb and resource ("Delete an opportunity") and clarifies the CRM synonym "deal", so the agent knows exactly what object is affected. It does not distinguish itself from other delete-tools or from update-opportunity-tool, but the resource naming makes confusion unlikely.

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 delete versus update/close an opportunity, no prerequisites (permissions, ownership), and no recovery instructions despite the parenthetical "soft delete". The agent must infer everything about when this is the right 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?

The annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known. The description's one added contribution is '(soft delete)', which tells the agent the record is not permanently erased—genuinely beyond what the annotations say. However it omits whether related records (notes, tasks, opportunities) are affected or whether a restore path 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?

A single front-loaded sentence with no filler; the most important qualifier (soft delete) is placed at the end but is still within the same sentence. Appropriate size for a simple single-parameter 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?

An output schema exists, so return values need not be explained. For a destructive operation, though, the definition should say whether the deletion cascades to related entities or is recoverable—the soft-delete hint gestures at recovery but leaves it ambiguous.

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

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

There is a single parameter with 100% schema description coverage, so the schema already fully documents 'id'. The description adds no format, source, or validation detail beyond it, which is the expected baseline when the schema does the work.

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

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

States a specific verb (delete) and resource (person/contact) in the CRM, and the parenthetical clarifies that 'person' means contact. It is distinguishable from siblings like delete-company-tool by resource, though it does not explicitly route to them.

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

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

There is no guidance on when to use this versus update-people-tool or the other delete-* siblings, and no prerequisites or warnings stated. The agent must infer usage entirely from the tool name.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds one genuinely useful trait beyond that: this is a soft delete, so the record is not permanently purged. It stops short of saying whether the task can be restored, whether it is removed from linked entities/notes, or what permissions are required.

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

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

A single short sentence with the resource and the key behavioral qualifier front-loaded; every word earns its place and there is no filler.

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

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

An output schema exists and annotations carry the destructive profile, so much of the burden is lifted. However, for a destructive mutation the description omits cascade effects (what happens to attached entities or notes) and whether the soft-deleted task is recoverable, which are the details an agent most needs before calling it.

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 there is only one required parameter ('id'), so the schema fully documents the input. The description adds no format hints (e.g., ID format) or error behavior for invalid/nonexistent IDs, which is the baseline expectation 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 (delete) and resource (task) scoped to the CRM, and the parenthetical '(soft delete)' clarifies the semantics of the operation. It does not explicitly distinguish itself from siblings like delete-company-tool or detach-task-from-entities-tool, but the name/description pairing makes the target unambiguous.

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

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

There is no guidance on when to delete versus when to use detach-task-from-entities-tool or update-task-tool, nor any stated prerequisites. The agent must infer that this removes the task record entirely rather than unlinking it from an entity.

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 destructive=true and idempotent=true, so the safety profile is largely covered. The description still adds useful context by specifying that specified links are removed, clarifying that the note itself is not deleted.

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

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

Two short sentences with the operation and scope front-loaded. There is no filler, and every phrase contributes to identifying the action and what it removes.

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 has rich annotations and an output schema, and the description sufficiently explains the core mutation: removing specified relationship links from a note. It is only missing minor operational context such as permissions or partial-failure behavior, which are not essential for correct invocation.

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

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

Schema description coverage is 100%, so the parameter meanings are already fully documented in the schema. The description adds no parameter-specific syntax, constraints, or behavior beyond what the schema provides, which is the baseline for complete 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 uses a specific verb ('Detach') and resource ('a note') plus explicit target entity types ('companies, people, or opportunities'). It also clarifies 'Removes specified links,' distinguishing this relationship removal from deleting or updating the note 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?

It states what the tool does but gives no explicit when-to-use guidance, exclusions, or alternatives such as attach-note-to-entities-tool or delete-note-tool. The appropriate use case is only implied by the action itself.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description reinforces removal ("Removes specified links") but does not clarify the key behavioral question for a destructive tool: that only the association is severed while the task and the linked records survive, nor what happens if some IDs are invalid.

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

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

Two short sentences with the destructive action front-loaded. "Removes specified links" partially restates "Detach", so it is not perfectly economical, but nothing is buried 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?

An output schema exists and annotations are rich, so return values and safety need no explanation here. What is missing is the scope boundary: whether this tool also deletes the task or the detached records, which is the main ambiguity an agent faces on a destructive detach operation.

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

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

Schema coverage is 100%, so the baseline is 3. The description slightly exceeds that by restating the entity-type mapping at the top level (companies, people, opportunities, users-to-unassign), which helps an agent match intent like "unassign a user" to the assignee_ids parameter during selection.

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 (detach) and resource (task relationships) plus the four relationship types affected, which is enough to place it against attach-task-to-entities-tool and detach-note-from-entities-tool. It stops short of naming those siblings explicitly, so it is clear but not fully differentiated.

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

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

Usage is only implied: an agent can infer this is the tool for removing links rather than deleting the task. There is no statement of prerequisites, no guidance on when to prefer delete-task-tool or update-task-tool instead, and no note on needing at least one of the optional ID arrays.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds only that it returns a single record, saying nothing about how it behaves on an invalid or unresolvable URL, or whether the URL must match an existing record. With annotations carrying the load, a 3 is appropriate.

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

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

Two short sentences with the core action front-loaded and no filler. The second sentence is slightly opaque ('ChatGPT Company Knowledge citations'), but it does carry the usage hint rather than 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?

Low-complexity read tool with a single documented parameter, an output schema that covers the return value, and annotations covering safety. The main remaining gap — which record types are resolvable and what happens on failure — is modest 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?

There is one parameter with 100% schema coverage; the schema already explains that the URL comes from the search tool or a browser-copied Relaticle URL. The description's phrase 'canonical URL' merely echoes it and adds no new meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Fetch a single CRM record by its canonical URL.' This is clear, but it does not distinguish itself from the typed getters in the sibling list (get-company-tool, get-people-tool, get-note-tool). An agent cannot tell from the description whether this is a generic shortcut across entity types or something else entirely.

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?

'Pair with the search tool for ChatGPT Company Knowledge citations' implies the workflow — search first, then fetch — but it never says when to choose this over the per-entity get-*-tool siblings. Usage is implied rather than stated, and there are no 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 declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety bar is met without prose. The description adds only that results include "full details and relationships," without saying whether relationships are included by default or require the include parameter, and without mentioning the 25-record truncation that the schema notes.

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. Nothing is repeated from the title and every phrase carries information.

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

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

With an output schema and full annotation coverage, most of the burden is already handled elsewhere. However, the phrase "with full details and relationships" is mildly ambiguous about whether relationships are always returned or gated behind include, which is the one thing an agent would want clarified.

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 id and include are already documented at the field level, which sets the baseline at 3. The description's "relationships" phrasing gestures at include but adds no syntax or format detail beyond the schema.

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

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

States a specific verb (Get) and resource (a single company), plus the lookup key (by ID). It is clearly distinct from list-companies-tool in meaning, though it never names the sibling explicitly.

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

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

"A single company by ID" implies this is the by-ID retrieval path versus a list/search tool, but there is no explicit when-to-use, when-not-to-use, or named alternative. 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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds substantive behavioral context beyond that: it scopes the result to one entity type and to *active* custom fields, and tells the agent the payload includes choice options, filters, and relationships — useful for planning downstream calls. It does not, however, say what happens for an unknown or unsupported entity type.

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

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

One sentence, front-loaded with the verb and scope, and every clause (custom fields, choice options, filters, relationships) contributes to predicting what comes back. Nothing to trim.

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 an output schema present the description need not explain return values, and annotations cover the safety profile, so the definition is largely self-sufficient for a single-parameter read tool. The only gap is the unresolved overlap with list-custom-fields-tool, which leaves selection ambiguous in some cases.

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 single parameter already lists the valid entity types ('company, people, opportunity, task, note'). The description's phrase 'one CRM entity' is consistent with the schema but adds no syntax or selection detail beyond it, 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 ('Get the current workspace schema for one CRM entity') and enumerates what the schema contains: active custom fields, choice options, filters, relationships. It is clearly distinct from the CRUD entity tools, though it does not distinguish itself from the near-sibling list-custom-fields-tool, which overlaps on custom-field metadata.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no named alternative. The closest sibling, list-custom-fields-tool, is never mentioned, so an agent has to infer which of the two to call when it only needs custom-field information.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds one genuine behavioral detail – that task due status is user-timezone-aware – but says nothing about aggregation scope, such as whether archived or deleted records are included in the counts.

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

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

A single dense sentence that front-loads the verb and lists outputs in order of importance. Every clause carries information; there is no filler.

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

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

With no parameters, full annotation coverage, and an output schema that documents return values, the description covers everything essential. The only shortfall is the undisclosed scope of the counts, but that is a minor gap for a zero-argument summary 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. Nothing in the description is needed to disambiguate inputs.

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 enumerates exactly what is returned: workspace record counts, pipeline totals by stage, and timezone-aware task due status. This clearly separates it from the sibling list-* and get-*-tool family, which return individual records rather than aggregates.

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

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

Usage is only implied – the enumerated metrics suggest a dashboard/overview use case, but the description never says when to prefer this over list-people-tool, list-opportunities-tool, or aggregate-opportunities-tool. No exclusions or prerequisites are given.

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

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

Despite annotations already covering read-only/idempotent safety, the description adds substantial behavioral detail: draft/outbox inclusion, conditional availability of body_text and attachments based on access level, body truncation flagging, and a prompt-injection warning about treating body content as data. This is exactly the kind of context annotations cannot convey.

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

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

The description is front-loaded with the core operation, then layers access, truncation, and prompt-injection guidance in tight, purposeful sentences. Every sentence earns its place, with no filler or repetition.

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

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

An output schema exists, so return-value explanation is not needed. The description covers the conditional return behavior (access level, truncation) and operational caveats that matter for a single-email read, making it complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the single `id` parameter is fully documented in the schema. The description reinforces that the ID can reference synced, sent, draft, or outbox mail, but adds no syntax or format detail beyond what the schema provides.

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

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

The description opens with a precise verb+resource: 'Read one email by ID.' It immediately scopes the resource to synced mail, sent mail, and the user's own drafts/outbox emails, which distinguishes this single-item read from the list-emails-tool 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?

Usage is clear: read a single email when you have its ID, and the schema points to the list emails tool as the ID source. There is no explicit when-not-to-use or named alternative beyond the implicit single-vs-list distinction, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured fields. The description adds a hint about returned relationship data, but nothing about behavior on a missing/invalid ID or how expansion limits are surfaced.

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

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

A single front-loaded sentence with the resource, lookup key and return scope, and no filler. Every clause carries information.

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

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

With an output schema present and both parameters fully described, the description does not need to explain return values, and annotations cover safety. A brief note on behavior for an unknown ID would close the remaining gap.

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

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

Schema description coverage is 100%, and the schema itself documents both `id` and the `include` expansion semantics including the 25-record truncation limit. The description adds no 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 ("Get a single note by ID") plus the scope of the return ("full details and relationships"), which separates it from list-notes-tool and from the other get-*-tool resources. It doesn't explicitly name a sibling, so it stops just short of a 5.

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

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

Usage is only implied: the phrase "by ID" signals the precondition that the caller already has a note identifier, which in turn points away from list-notes-tool and search. There is no explicit when-to-use/when-not statement and no named 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety behavior is fully covered structurally. The description adds that results carry 'full details and relationships', but says nothing about error behavior for an unknown ID or the truncation limit that applies to expanded to-many relations.

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 the resource and lookup key front-loaded and no filler. Nothing in it could be cut without losing information.

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

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

With a full output schema and complete annotations, the description only needs to convey scope and it does so accurately. The one missing piece is what happens when the ID does not match, which is minor given 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 both 'id' and 'include' are already documented, including the 25-record truncation rule for to-many expansions. The description mentions relationships generically but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get a single opportunity by ID') and scopes it to one record, which implicitly separates it from list-opportunities-tool and search. It does not name any sibling explicitly, so differentiation rests on the word 'single'.

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

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

Usage is only implied: an agent can infer this is for fetching one known opportunity ID, and the mention of relationships hints at using 'include'. There is no explicit when-to-use, when-not-to-use, or pointer to list-opportunities-tool / search for discovery-style 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds that the response includes 'full details and relationships', which hints at response shape, but says nothing about behavior on missing IDs, permission requirements, or cost of expanding relationships (which the schema covers only for the include param).

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

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

A single sentence with the key constraint ('by ID') and the payoff ('full details and relationships') front-loaded. Nothing extraneous.

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

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

With an output schema present, annotations covering safety, and full parameter documentation, the description does not need to explain return values. It is nearly complete for a simple getter; the only missing piece is guidance for not-found or ID-resolution cases.

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 id and include parameters are already documented, including the 25-record truncation note. The description adds only the loose phrase 'with full details and relationships', which does not clarify the include semantics beyond the schema 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 and resource ('Get a single person by ID') plus a scope note ('full details and relationships'), which distinguishes it from the sibling list-people-tool. It never names the sibling explicitly, so the differentiation is implied rather than stated.

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

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

'By ID' implies the caller must already have an identifier, which implicitly separates this from list/search flows. However, there is no explicit guidance on when to prefer list-people-tool versus this tool, nor on what to do when the ID is unknown.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The description adds that results include 'full details and relationships', hinting at response breadth, but says nothing about behavior when the ID does not exist or about default relationship expansion.

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

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

A single sentence with zero filler, front-loading the resource and the lookup key. Nothing is repeated from the title or schema, and it is sized appropriately for a simple fetch 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?

With an output schema present, the description need not explain return shape, and both parameters are documented in the schema. The remaining gap is minor: no statement about missing-ID behavior or whether relationships are expanded by default versus only via `include`.

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 `id` and `include` are already documented, including the 25-record truncation behavior for to-many expansions. The description's 'relationships' wording loosely gestures at `include` but adds no syntax, defaults, or valid relationship names 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 ('Get a single task by ID') plus the scope of what comes back ('full details and relationships'). It implicitly distinguishes itself from list-tasks-tool by requiring a single ID, but never names the sibling retrieval tools explicitly.

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

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

Usage is only implied: 'by ID' signals this is for fetching a known task rather than enumerating tasks, which nudges an agent away from list-tasks-tool. There is no explicit when-to-use/when-not guidance, no mention of alternatives like search or list-tasks-tool, and no note on what to do if the ID is unknown.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered; the description still earns credit by adding the full channel vocabulary, the null-when-unrecorded semantics, and the fact that results are rendered in the caller's timezone. It stops short of disclosing pagination behavior or result volume limits, which the schema only partially covers.

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

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

A single dense sentence that front-loads the actor/record/channel/time/diff axes and closes with the timezone caveat. Every clause carries information an agent cannot get from the schema alone.

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?

An output schema exists, so return-shape explanation is unnecessary, and all four optional parameters are fully documented in the schema. What remains missing is selection guidance against the many sibling read tools, which matters given how many listing tools share this namespace.

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% — days, page, record_id, and record_type all carry their own descriptions including defaults and maxes. The description adds nothing parameter-specific (the timezone note describes output, not an input), 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 a precisely scoped resource: change history across CRM records, with actor, channel, timestamp, and field-level diffs. That clearly separates it from the entity-listing siblings (list-companies-tool, list-people-tool), but the description never names an alternative, so the differentiation is implicit rather than stated.

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

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

The description implies the use case (auditing who changed what and when) but gives no explicit when-to-use / when-not-to-use guidance and never routes the agent toward or away from siblings such as get-crm-summary-tool or the per-entity list tools. Usage is inferable, not stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds only that results are filtered and paginated; it does not mention page-size caps, page limits, or how the two interact, which the schema covers instead.

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

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

A single well-formed sentence, front-loaded with the resource and scoped by the two modifiers. No filler and no restatement of the 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?

An output schema exists and the filter schema is exhaustive, so most burden is offloaded. However, for a list tool with 5 params and nested objects, the description gives no hint about result ordering, the 25-per-page cap's practical effect on large result sets, or that to-many expansion must go through show tools—gaps an agent would hit at call time.

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

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

Schema description coverage is 100%, including a very detailed filter grammar, so the schema carries the full burden. The description adds nothing beyond naming the existence of filters and pagination—the baseline 3 is appropriate.

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

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

The description gives a specific verb and resource ('List companies in the CRM') plus the modifiers (filters, pagination). It is easily distinguished from create-company-tool and get-company-tool by the verb, though it never names a sibling explicitly.

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

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

Usage is only implied: 'with optional filters and pagination' suggests this is the collection-retrieval endpoint, but there is no statement about when to choose it over get-company-tool (single record) or list-people-tool (other entity types), and no 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 declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds substantive context beyond that: that inactive field definitions are returned and that option labels are configured values, which shapes how an agent interprets results. Pagination behavior is left 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?

Two sentences, both load-bearing, with the main scope statement front-loaded and the disambiguation second. There is no filler.

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

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

With an output schema present, return values needn't be spelled out, and the four optional params are fully documented in the schema. The only residual gap is the lack of explicit guidance on combining entity_type with active filtering, which is minor for a simple 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%, so every parameter is already documented, including the default-includes-inactive behavior of 'active'. The description's mention of inactive fields largely restates what the schema says and adds no new syntax, format, or edge-case guidance. 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 concrete verb and resource ('List workspace custom-field definitions') and adds scope detail: inactive fields and configured option labels are included. It also names the sibling it is not ('get-crm-schema-tool'), 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?

Explicitly routes the agent to get-crm-schema-tool when the active write schema is wanted, which is the key ambiguity in this tool family. It does not state when this tool should be avoided outright, but the comparative framing gives clear 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 cover readOnly, idempotent, non-destructive, closed-world, so the bar is lower; the description still adds real value by explaining the `can_send` flag semantics and the reconnect-only-receive case. It doesn't state auth prerequisites or whether reconnecting is done elsewhere, a minor gap.

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

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

Three short sentences ordered by importance: what it lists, how to use the result, then the one non-obvious field. No filler and nothing buried.

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

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

For a zero-parameter read tool with an output schema and full annotation coverage, this is complete — the description covers purpose, downstream linkage, and the one field whose semantics an agent would otherwise misread.

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 by rule. The description usefully explains the meaning of an output field (`can_send`) and the downstream use of `id`, which goes beyond structured data.

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 the mailboxes...connected') with scope ('the current user', 'in this workspace'), which cleanly separates it from the list-emails-tool sibling that lists messages rather than accounts. An agent can pick the right one without opening the schema.

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

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

Explicitly routes the agent forward: use the returned `id` as `connected_account_id` when drafting or sending, which links this tool to create-email-draft-tool/send-email-tool. It stops short of saying when NOT to call it (e.g., caching vs. re-checking before send), so it is not a full 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description correctly spends its budget elsewhere: the three-tier access model, the reason subject/snippet come back null, the warning that a page may be shorter than per_page, and an explicit prompt-injection caution. The only real gap is that it doesn't state total-count or end-of-results behavior when paging.

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 scope and ordering, then the status vocabulary, then the access/null contract, then the injection warning. Nothing repeats the schema verbatim and every sentence changes how an agent would read the results.

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?

Output schema exists, yet the description still explains the one genuinely confusing aspect of the payload (access tiers driving null subject/snippet), so an agent won't mistake redaction for missing data. With 10 optional params fully documented in schema, nothing material 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 coverage is 100%, so baseline is 3, but the description adds the access model that explains why filtering and reading behave differently per row, which is meaning the schema doesn't supply. It also enumerates the status values in prose, which largely restates the enum, keeping this just above 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 and resource plus the exact scope: "emails the current user may see, newest first: synced and sent mail, plus the user's own drafts and outbox." That scope plus the ordering clause cleanly separates it from get-email-tool (single message) and list-email-accounts-tool (accounts, not messages) without either schema being opened.

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 establishes context for browsing mail but never says when to prefer this over get-email-tool for a known message, or over search-style siblings. Usage is implied by the scope sentence rather than stated as a rule, and no exclusions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that profile: it doesn't mention defaults, ordering, pagination limits, or how 'include' behaves, all of which would be useful 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?

It is a single front-loaded sentence with no filler. It is efficient, though its brevity means it omits context that would help an agent choose and configure 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?

An output schema exists and annotations fully cover safety, and the input schema fully documents the complex filter. The description is sufficient to identify the tool, but for a five-parameter tool with nested filter objects, it should say more about when to use it and how include differs from filtering.

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 page, sort, filter, include, and per_page are already thoroughly documented in the schema. The description only says 'optional filters and pagination' and adds no syntax or meaning beyond what the schema provides; 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?

The description states a specific verb and resource (list notes) and the scope (in the CRM), so an agent can identify the operation. It does not differentiate from siblings such as get-note-tool or list-activity-tool, and it doesn't clarify whether notes are listed globally or per entity.

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

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

There is no explicit when-to-use guidance, no conditions for choosing this over get-note-tool, and no mention of alternatives. The phrase 'with optional filters and pagination' hints at use cases but leaves all selection logic 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, destructiveHint=false and openWorldHint=false, so safety is fully covered. The description adds essentially nothing beyond that — no default ordering, no note that filters are applied server-side, no mention that a complex filter may need get-crm-schema-tool for custom field codes.

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. Nothing in the description is redundant or misplaced.

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?

An output schema exists, so return shape need not be described, and the five parameters are fully documented in the schema. Given the safety annotations and the rich filter schema, the description is sufficient for an agent to call this correctly — the only real gap is sibling routing, which is scored under usage guidelines.

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 filter parameter carries an extensive operator/logic specification, so the schema does the heavy lifting. The description adds no parameter-level meaning of its own; 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 opportunities/deals) and clarifies the CRM domain synonym, so an agent knows it retrieves a collection rather than a single record. It does not, however, distinguish itself from aggregate-opportunities-tool or get-opportunity-tool, which sit in the same sibling set.

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

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

'With optional filters and pagination' implies the browse/filter scenario, but there is no explicit guidance on when to choose this over aggregate-opportunities-tool (for counts/metrics) or get-opportunity-tool (single record by id). The agent must infer the boundary from the tool names alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds no behavioral context beyond those annotations, such as permissions, rate limits, pagination details, or edge cases, and it does not contradict them.

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. The size is appropriate given that the schema and output schema carry the detailed 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?

The output schema covers return values and annotations cover safety behavior, while the schema richly documents parameters. However, the description omits routing guidance among the many list/search/get siblings, leaving a meaningful gap for a minimal list tool.

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

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

Schema description coverage is 100%, so all five parameters, including the complex filter object, are already documented. The description only repeats 'optional filters and pagination' and adds no extra meaning or syntax beyond the schema, 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?

Names a concrete verb ('List') and resource ('people/contacts in the CRM') and states that filtering and pagination are supported. It does not explicitly differentiate this tool from sibling list tools or get-people-tool, so it stops short of 5.

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

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

The description gives no when-to-use or when-not-to-use guidance, and it names no alternatives such as search, get-people-tool, or list-companies-tool. It only implies that this tool is used for listing people.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the description carries a lighter burden. It still adds nothing beyond them: no default ordering, no statement of what a page returns or how totals are exposed, and no hint that filters must stay within complexity limits (that lives only in 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?

One short, front-loaded sentence with no filler; the core action and the two modifiers appear 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?

The output schema, full per-parameter docs, and safety annotations together cover most of what an agent needs, leaving only default sort order and result-count behaviour unexplained. The description is thin but the surrounding structured data is rich, so nothing critical is missing.

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

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

Schema description coverage is 100% and the filter parameter is documented in extreme detail, so the description's bare mention of 'filters and pagination' adds no meaning. 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 tasks) and adds the retrieval mode (filters, pagination). It is distinguishable from the create/update/delete task tools by verb and from the list-* family by resource, though it never explicitly names a sibling or contrasts with get-task-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?

Mentions optional filters and pagination, which implies 'use this to browse/filter many tasks', but there is no explicit when-to-use or when-not, and no pointer to get-task-tool for a single record or to a search 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 non-read-only, idempotent and destructive, so the description's real contribution is the non-obvious hold-clamping rule ('a time sooner than the hold is moved to the end of the hold'), which materially changes what value ends up being used. It still does not explain why the tool is flagged destructive or what happens for non-queued/other-user IDs, leaving a gap against the destructiveHint.

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

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

Two tight sentences with zero waste: purpose first, then the one behavioral caveat that changes agent behavior. Nothing is repeated from the schema or annotations.

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 an output schema present and annotations covering the safety profile, the description supplies the scope and the hold rule needed to call it correctly. It could still say what an invalid/non-queued ID returns, but no critical calling information 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 would be 3, but the description adds real constraint on the 'id' parameter: the target must be one of the current user's queued emails. The 'scheduled_for' parameter's clamping behavior is also described, going beyond the schema's bare 'ISO 8601 datetime to send at.'

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 ('Change when ... queued emails is sent') and scopes it to 'the current user's' queue, which separates it from draft-editing siblings like update-email-draft-tool. It never names the adjacent tools (cancel-email-tool, retry-email-tool) explicitly, so differentiation is implied by scope rather than stated.

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

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

Use is implied by 'queued emails' – the agent can infer this applies only to emails already scheduled, not drafts or already-sent mail. However, no explicit when-to-use/when-not conditions or redirects to cancel-email-tool or retry-email-tool are given, so the agent must infer the boundaries.

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 annotations (destructiveHint=true, idempotentHint=false), the description discloses the hold delay ('held for a few minutes first, like a new send') and the cancellation path via Relaticle notifications or Outbox, which an agent could not infer from structured fields. It does not explain why the operation is flagged destructive (e.g. whether the original failed email record is consumed), leaving one meaningful behavioral gap.

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

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

Three short sentences, front-loaded with the action, then the behavioral caveat, then the eligibility constraint. Every sentence contributes a distinct fact 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?

An output schema exists so return values need no explanation, and the description covers the precondition, the delay window, and the cancellation route. It stops short of clarifying the state of the original failed email after retry, which matters given the destructive flag.

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 single `id` parameter is documented in the schema as the ID returned by the send tools or list emails tool. The description adds no additional 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 and resource ('Queue ... failed emails again') with explicit scope ('one of the current user's') and precondition ('status is failed'). An agent can distinguish this from send-email-tool, cancel-email-tool, and reschedule-email-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?

Gives a clear eligibility gate ('Only an email whose status is failed can be retried') and notes the user can cancel afterwards, which implies the relationship to cancel-email-tool. It does not explicitly name an alternative tool or state when to prefer reschedule-email-tool instead, so sibling routing is implied rather than spelled out.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive behavior, so safety is covered. The description adds genuinely new context with 'Returns canonical URLs suitable for ChatGPT Company Knowledge citation,' which tells the agent about output shape and downstream use, but says nothing about the per-entity limit cap or truncated/empty results.

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

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

Two sentences, zero filler, with the entity scope front-loaded and the return characteristic second. Nothing to cut.

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?

An output schema exists so return values needn't be explained, and parameter semantics are fully covered in-schema. The description would be complete except for the multi-entity pagination/limit interaction, which only appears in the schema's limit field.

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 are well documented in-schema (substring semantics, 255-char cap, default/max for limit). The description adds nothing beyond the schema, which is the correct baseline for 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 (search) and a clear scope: five named entity types. This differentiates it in practice from the many per-entity list-*/get-* siblings, though it never names them explicitly, keeping it 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 cross-entity scope implies the use case (finding records when you don't know which entity type holds them), but there is no explicit when-to-use vs. list-companies-tool/get-company-tool guidance and no stated exclusions or prerequisites.

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 destructive and open-world, and the description goes further: it explains that the draft is sent exactly as stored including in-app edits, that the draft is removed from Drafts, that recipients are external, and that there is a few-minute hold cancellable from notifications or Outbox. That is real behavioral context an agent cannot get from the annotations alone.

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

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

Three sentences, front-loaded with the action and the side effect (removal from Drafts). Every sentence carries information, though the opening sentence is long and packs the send semantics and the deletion together.

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

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

For a non-idempotent, destructive send with an output schema, the description covers what is sent, who receives it, what is destroyed, and the cancellation window. 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 both draft_id and scheduled_for are already documented, including the rule that an earlier time is pushed to the end of the hold. The description adds nothing parameter-specific beyond that baseline, which is acceptable but not additive.

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

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

States a specific verb and resource: sends the current user's saved draft verbatim and removes it from Drafts. That is unambiguous and clearly distinct from the draft-creation/update tools. It stops short of explicitly contrasting with the sibling send-email-tool, which also dispatches mail, so sibling differentiation is inferred rather than stated.

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

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

Gives a clear precondition ('only when the user asked for it') because the email reaches people outside the workspace, which is exactly the kind of gating an agent needs. It also flags that the send is cancelable during a hold, implying an alternative path, though it never names cancel-email-tool or reschedule-email-tool as the tools to reach 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?

Discloses behavior that annotations cannot convey: external reach (openWorldHint restated with meaning), a multi-minute hold before delivery, and cancellability from Relaticle notifications or Outbox, which softens the destructiveHint=true. It omits the 20-recipient cap and signature default, though both are in the schema. Strong added context, short of 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?

Five short sentences, front-loaded with the action and the consent gate before mechanics and alternatives; nothing is buried. Slight redundancy where the body-format sentence repeats the schema description exactly.

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-blast-radius send tool with annotations and an output schema already present, the description supplies the missing decision-relevant context: consent requirement, delay window, cancellation path, and sibling routing. Only the recipient limit and signature behavior go unmentioned, and those live in the schema.

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

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

Schema description coverage is 100%, so all nine parameters are already documented; the description mostly restates them ('body as plain text or markdown' duplicates the schema). 'Pass scheduled_for to send later' adds a use case rather than new syntax, so the marginal value is modest. 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 ('Send an email as the current user from one of their mailboxes') plus the scope of the send (reaches people outside the workspace). It is clearly distinguishable from create-email-draft-tool and send-email-draft-tool, which it names directly.

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

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

Gives an explicit gating condition ('call this only when the user asked for it') and names the alternative with the selecting condition ('Prefer the create email draft tool when the user wants to review before sending, then send that draft with the send email draft tool'). When-to-use and when-to-use-something-else are both 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, destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is largely carried by structured data. The description adds the schema-lookup prerequisite but does not disclose a key behavior for a destructive mutation: whether omitted fields are preserved or cleared, or what happens to fields not supplied. That is a meaningful gap given destructiveHint=true.

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

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

Two short sentences, front-loaded with the core action and followed by the one actionable prerequisite. No waste, though the second sentence largely duplicates the custom_fields schema text rather than adding new information.

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

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

An output schema exists and the annotations plus 100%-covered input schema are rich, so much of the burden is off the description. Still, for a destructive, idempotent update tool with a required id and nullable owner field, the description omits partial-update semantics and failure behavior, leaving it only minimally 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 baseline is 3. The description only reinforces the crm-schema requirement already stated in the custom_fields schema description and adds no new semantics (e.g., partial-update behavior, null handling for account_owner_id) beyond what the schema already documents.

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

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

States a specific verb and resource ('Update an existing company in the CRM'), which cleanly separates it from create-company-tool and delete-company-tool. It does not explicitly name any sibling, but the verb/resource pair is unambiguous against the many other update-*-tool 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?

It gives one concrete operational prerequisite — read the crm-schema resource before using custom_fields — which is genuinely useful routing guidance. However, it offers no when-to-use vs. when-not guidance (e.g., when to use get-company-tool first, or that this only updates vs. creates), leaving usage context 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?

Goes well beyond the annotations by disclosing the key destructive behavior — arguments fully replace mailbox, recipients, subject and body — plus that attachments survive, nothing is sent, and a signature is injected unless include_signature is false. This tells the agent exactly what data will be lost on an idempotent-but-destructive write.

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 the core action and the most costly gotcha (replacement semantics) first. No filler; every sentence carries either scope, side effect, or format 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?

Given nine parameters, a 100%-covered schema, an output schema, and destructive annotations, the description supplies the remaining critical context: replace-vs-merge behavior, attachment preservation, no-send guarantee, and signature default. Nothing needed to invoke it safely is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: that omitted fields are wiped rather than preserved, that body may be plain text or markdown, and the signature side effect of include_signature. These are behavioral constraints the schema alone does not convey.

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

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

States a specific verb and resource ('Rewrite one of the current user's saved drafts') and immediately distinguishes it from sending via 'Nothing is sent.' An agent can tell this apart from create-email-draft-tool and send-email-draft-tool without inspecting 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?

The explicit replace-semantics warning ('pass everything the draft should keep') is a strong usage instruction that governs how to call it. It does not name sibling alternatives (create/send/delete draft tools), so routing guidance is slightly incomplete, but the when-to-use 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 declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the safety profile is carried by structured data. The description adds only the schema-discovery prerequisite, which is itself repeated in the custom_fields parameter description, and says nothing about partial-update behavior or what is lost when arrays are passed as [].

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

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

Two short sentences, front-loaded with the action, no filler or restated title. Every sentence carries information an agent can act on.

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 an output schema, rich annotations and full schema coverage, most of the burden is lifted off the description. Still, for a destructive mutation with six parameters and link-replacement semantics, the description does not touch on what changes are destructive or how linking behaves, leaving that entirely to the schema.

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

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

Schema description coverage is 100% and each parameter documents its own semantics, including the "omit to leave unchanged, pass [] to remove all" rule and the exact-field-code warning. The description's only parameter-related sentence duplicates what the schema already states, so it adds no meaning 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?

The description states a specific verb and resource ("Update an existing note") and scopes it to the CRM, so it is clearly distinct from create-note-tool and delete-note-tool by inference. It never names a sibling explicitly, so the differentiation is implicit rather than stated.

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

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

"Use the crm-schema resource to discover available custom fields" is a genuine prerequisite, but it only covers custom_fields. Nothing says when to use this instead of attach-note-to-entities-tool or detach-note-from-entities-tool, which overlap with the people_ids/company_ids/opportunity_ids linking parameters.

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 destructiveHint=true and idempotentHint=true, so the agent knows this mutates and overwrites, but the description never explains what 'destructive' means here — whether omitted fields are preserved or cleared, or whether overwriting a custom field loses prior values. The only behavioral content is the schema pointer, which the input schema already states verbatim.

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

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

Two short sentences, front-loaded with the operation and followed by the prerequisite. Nothing is padded, though the second sentence largely restates what the schema property already says, so it is not perfectly economical.

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

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

For a destructive mutation with nested custom_fields, an output schema, and full param documentation, the main missing piece is update semantics — partial vs full replacement and the consequences of the destructive flag. The resource pointer is present, but the risk profile an agent needs before writing is not.

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

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

Schema description coverage is 100% and the custom_fields parameter description already spells out the 'read crm-schema first, exact field codes, unknown codes rejected' rule. The description's version of that instruction adds nothing new, so this sits at the baseline for a fully documented 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 ('Update an existing opportunity (deal) in the CRM'), and the '(deal)' gloss clarifies domain vocabulary. It doesn't explicitly contrast with create-opportunity-tool or update-company-tool, but the create/update distinction is unambiguous from the name and verb.

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 gives a real prerequisite for custom fields (read the crm-schema resource first), which is actionable guidance. However, there is no statement of when to prefer this over siblings like update-company-tool, or what conditions make an update inappropriate.

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