Tommos

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

Annotations already cover the safety profile (readOnly=false, idempotent=true, destructive=false), so the bar is lower. The description adds real context beyond them: sync timing ('from the next sync'), the 30-day backfill window, that new-lead discovery is off by default, and that re-adding a stopped mailbox resumes rather than errors.

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 action is front-loaded and each sentence adds a distinct fact (prerequisite, sync/backfill, alternative, default, resume). The prose is somewhat flowery and dense ('its letters join the leads' timelines'), but nothing is redundant.

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

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

For a one-parameter, non-destructive mutation with no output schema, the description covers prerequisites, side effects, defaults, the alternative tool, and re-add semantics. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% for the single 'address' parameter, so the schema already carries the meaning. The description adds no format or syntax detail beyond the schema's own example, 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 (add) and resource (a mailbox of the company's Google Workspace) plus the scope it joins (what this workspace reads). It explicitly distinguishes itself from the sibling link_to_connect_your_mailbox, so an agent can route correctly without opening the schema.

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

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

Gives the prerequisite (Workspace admin has granted domain-wide delegation) and names the alternative path (a person connecting their own mailbox via sign-in with link_to_connect_your_mailbox). When-to-use and when-not are both explicit.

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

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

Annotations already declare non-destructive, idempotent, open-world behavior. The description adds meaningful non-annotated context: the tool returns a DNS TXT record to publish, and the domain is inactive until proven – behavior the agent could not infer from the structured fields 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 tight sentences, front-loaded with the action, then the DNS outcome, then the constraint. Every sentence carries distinct information with no 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?

For a single-parameter tool with no output schema, the description covers what it does, what it returns (the TXT record), and the follow-up dependency, which is everything an agent needs to call it correctly.

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

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

Only one parameter with 100% schema coverage, so the schema already documents the 'domain' field. The description reinforces that the domain identifies where mail will be sent from but adds no format or validation 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?

Specific verb (add) plus resource (sending domain) with clear scope: 'Add a domain the workspace will send from.' It also distinguishes itself from the sibling prove_a_sending_domain by naming it as the follow-up step.

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?

Establishes the workflow context ('then prove it with prove_a_sending_domain') and the operational constraint ('No letter leaves from a domain until it is proven'), telling the agent this is the setup half of a pair. No explicit when-not-to-use, but the sequencing 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 this is a non-read-only, non-idempotent write (readOnlyHint=false, idempotentHint=false). The description adds genuinely new behavioral detail beyond the annotations: pages are attributed to "whoever adds it," and nesting is bounded to three levels. It stops short of stating append-vs-replace behavior or permission requirements.

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

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

Purpose is front-loaded in the first clause, followed by the object shape and the workflow hook; the whole thing is a tight, information-dense block. The "as the Import's Add pages does" analogy is mildly referential but still earns its place by anchoring the behavior.

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

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

For a batch mutation with an opaque schema and no output schema, the description covers the essential object structure and attribution. It omits edge cases an agent might need: whether referenced parents must pre-exist, error/partial-failure behavior on a multi-page batch, and the return value.

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 0% and the single parameter is an untyped array of objects, so the schema gives almost nothing. The description compensates well by spelling out the per-page shape { title, body, parent, children } and the exact meaning of body and parent, which the schema cannot 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 ("Add pages to the Playbook") and ties it to a known flow ("as the Import's Add pages does"), so an agent grasps the operation immediately. It also implicitly distinguishes itself from propose_playbook_pages, though it never explicitly contrasts with the single-page sibling write_a_playbook_page.

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 instruction "Pass the pages propose_playbook_pages answered, as kept or changed" establishes a clear workflow precondition (this tool consumes the proposal output). However, there is no explicit when-not-to-use guidance, and no contrast against write_a_playbook_page, so an agent must infer which page-writing tool to pick.

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

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

Annotations already flag destructive=true and idempotent=true, but the description goes well beyond them: it enumerates exactly what is erased (letters, their timeline rows, mail marks, an emptied conversation), notes the response reports the amount erased, and states the connected-mailbox refusal case and authorization requirement. This is the substantive behavioral context annotations cannot carry.

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

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

Front-loaded with the core action, and every clause carries information. The em-dash enumeration of erased artifacts makes the second sentence long and slightly dense, but nothing is redundant filler.

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

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

For a single-parameter destructive mutation with no output schema, the description covers the action, side effects, refusal case, permission requirement, and even the return value ('the answer says how much'). Nothing an agent needs to call it correctly is missing.

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

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

With one parameter at 100% schema coverage the baseline is 3, but the description adds semantics the schema lacks: it accepts an address (jane@investor.com) or a domain (investor.com), and explicitly notes that a domain entry also covers its subdomains. That subdomain scoping is real added meaning.

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

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

Names a specific verb (add an address/domain) and a specific resource (the mail Tommo won't read), and clearly delineates scope: address entries and domain entries including subdomains. An agent can distinguish this from remove_from_the_mail_tommo_wont_read and read_the_mail_tommo_wont_read at a glance.

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 the operative context ('From then on no letter... is fetched, read or kept'), a prerequisite ('For a signed-in admin or owner'), and an explicit refusal condition ('Refused for an entry that covers a connected mailbox itself'). It does not name sibling alternatives such as block_a_sender or remove_from_the_mail_tommo_wont_read, so it stops short of full when-not guidance.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), yet the description adds material context beyond them: the auth requirement, the audit trail ('The record says who approved it and that it was through MCP'), and the conditional suppression rules for test records, paused leads, and unconfirmed owners. It stops short of naming error or failure behavior for the mutation itself.

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

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

The core action is front-loaded in the first clause, which is good, but the remainder is a dense run-on paragraph whose archaic metaphors ('what it carries is done', 'struck names the departures struck on an errand') cost more comprehension than they earn. Substantive content is present but padded with stylistic phrasing.

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

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

For a 7-parameter, nested-object mutation tool with no output schema, the description covers the auth precondition, the resulting side effects, the audit record, and the per-parameter meaning of the optional edit/answer/file fields. It omits failure handling and does not revisit idempotency beyond the annotation, so it is nearly but not fully complete.

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

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

With 71% schema description coverage the baseline is 3, but the description genuinely adds semantics the schema lacks, notably that edits target a step 'by its place on the card, 0 the first' (zero-based index) and where a submitted file is stored ('the customer's folder of the company's Drive'). It explains answer/picked/struck in narrative form, though parts duplicate the schema and the archaic phrasing reduces precision.

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 ('Approve a card as the signed-in person') and spells out the two concrete effects: a letter goes out and a change lands on the record. It implicitly differentiates itself from siblings like reject_a_card or set_a_card_aside by centering on the approval action, but never names those alternatives, and the heavy metaphor ('a letter leaves', 'on the wire's own rules') makes the purpose clear only after parsing.

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 real precondition ('Only a signed-in person approves; a key cannot') and conditional behavior for when the action has no outward effect (test record, paused lead, unconfirmed owner). However, it never says when to choose approval over the sibling refusal/rejection tools, so the routing guidance is only implied.

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

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

Annotations only declare the generic mutation profile (readOnlyHint=false, idempotent=false, openWorld=true). The description adds real behavioral context beyond them: nothing is charged by the call, the owner pays on that page, a letter is sent to owners, and two specific refusal preconditions. This is exactly the value-add the annotations cannot supply.

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

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

Purpose and side effect are front-loaded in the first clause, followed by refusals. The em-dash-heavy single-sentence construction is dense but every clause carries information; it could be split for readability without losing content.

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

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

For a mutation tool with no output schema, the description covers side effects, preconditions, and the billing alternative. What it doesn't say is what the caller receives (the link itself? a confirmation?) or any permission requirements beyond owner confirmation, which leaves a minor gap.

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

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

Schema description coverage is 0% and both params are bare enums, so the description must compensate. It defines each plan tier ('book' = discovery call booked, 'close', 'sign') and covers interval ('paid by the month or the year'), though the interval wording is looser than the enum values and doesn't map 'month'/'year' explicitly.

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 (ask owners to choose a plan) with a concrete side effect: generating the payment-page link and sending it to the workspace's owners in a letter. The plan tiers and intervals are enumerated, so an agent can distinguish this from every sibling, none of which sends owner billing correspondence.

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

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

Gives clear when-not conditions (refused while the owner has not confirmed their address; refused for a workspace already paying) and names the alternative path (move between plans in the billing portal, which only the owner opens). It stops short of an explicit positive trigger statement, but the conditions are unambiguous.

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

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

Annotations declare the safety profile (destructiveHint=true, idempotentHint=true), and the description adds real substance beyond them: all of the contact's addresses are blocked, the lead is disqualified and deleted, deletion is recoverable within 30 days, and the card is refused with the block as the reason. This is exactly the destructive-scope context an agent needs.

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

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

A single front-loaded sentence that states the action first, then enumerates its effects via a colon-delimited list. No filler, no restatement of the name, and every clause carries distinct information.

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

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

For a destructive mutation with no output schema, the definition covers the action, the full side-effect chain, reversibility window, and the optional parameter's effect, while annotations carry the idempotency and safety signals. An agent has enough to invoke it correctly without further context.

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

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

Schema coverage is 100%, so the schema alone justifies a baseline 3. The description goes further by explaining card_id's role (the card is refused, using the block as the refusal reason) and confirming that both contact addresses and the optional card are affected, adding meaning beyond the schema's terse field descriptions.

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 ("Block a lead's sender") and pins the semantics to a known product behavior ("as Flow's Block does"). The action is unambiguous and clearly distinct from unblock_a_sender, but the description never explicitly contrasts itself with that sibling, so it stops short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use statement and no named alternative such as unblock_a_sender. Usage is only implied through the described consequences (disqualification, deletion, card refusal), which the agent must reason about 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 idempotentHint=true and destructiveHint=false, so the agent knows repeated calls are safe and nothing is destroyed. The description adds the state transition (set-aside -> open) but omits return shape, permission needs, or error conditions; with annotations carrying the safety profile, a 3 is fitting.

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 compact sentence with the object front-loaded; there is no filler beyond the somewhat redundant 'now', which technically adds nothing.

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

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

For a simple single-parameter state-toggle with no output schema and non-trivial annotations, the description is adequate but does not say how to locate set-aside cards or what a successful call returns, leaving minor gaps.

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

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

Schema coverage is 100% and the single card_id is documented in-schema as coming from list_open_cards, so the description adds nothing beyond the schema. 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 clear verb+resource ('bring a card back') and pins the source state ('that was set aside'), which implicitly distinguishes it from the inverse sibling set_a_card_aside. It stops short of naming that sibling or the resulting state explicitly, so an agent must infer the pairing.

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 precondition ('that was set aside') hints at when the tool applies, and the destination ('among the open cards') clarifies the intended end state. However, there is no explicit when-to-use/when-not guidance and no named alternative, so usage is only implied.

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

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

Annotations already declare not-read-only, not-destructive, not-idempotent; the description adds genuine behavioral context by explaining the outcome — the card returns to review where it can be changed and re-approved — and how the invalid-state case is handled. It doesn't discuss permissions or error text, but it goes beyond the annotations without contradicting 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?

Two sentences, front-loaded with the core action before the edge case. The em-dash and colon construction is dense but every clause (the two waiting states, the already-left case) earns its place.

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

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

No output schema exists, so the description carries return semantics — it explains that the card goes back to review and that an already-left letter is reported as such. That covers the key outcome an agent needs for a single-parameter state-change 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?

With one parameter and 100% schema coverage, the schema already documents card_id and points to list_open_cards as its source. The description adds no further syntax or format 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+resource (take back an approved letter not yet sent) and sharpens the scope with two qualifying states: waiting for the lead's hours or the sweep. An agent can distinguish it from state changes like reject_a_card or stop_a_card by the condition attached, 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?

Gives a clear when ('has not left yet' — waiting on lead hours or sweep) and a when-not ('a letter that has already left is answered as such'), so the agent knows the boundary. It stops short of naming an alternative tool for the already-sent case.

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

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

With annotations already declaring the mutation as idempotent and non-destructive, the description adds real behavioral constraints: role changes apply only to non-owner members and ownership transfer is explicitly excluded. It still omits whether a permission level is required or whether the member is notified.

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

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

Two tightly packed sentences with the core action and valid targets front-loaded. The second sentence is dense but every clause carries a real constraint, so little is wasted.

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

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

For a two-parameter mutation with annotations covering safety and idempotency and no output schema, the description supplies the key scope boundaries an agent needs. Remaining gaps (invoker permissions, side effects like notifications) are minor.

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

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

Schema coverage is 50%; user_id is documented in the schema, and the role enum is self-explanatory, but the description lists only admin/member/viewer while the enum also allows owner, so it neither explains the owner case cleanly nor adds syntax beyond the schema. Roughly baseline for partial 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 (change) and resource (a member's role) with the target values, so an agent knows exactly what operation is performed. It does not explicitly distinguish itself from siblings like remove_a_member or invite_a_person, which keeps 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 description gives genuine when-not guidance through scope limits (admins can't touch an owner, the sole Owner is never demoted, ownership transfer is out of scope), but it never routes the agent to an alternative tool or states prerequisites such as who may invoke it.

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

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

Beyond the annotations, the description discloses that the action is taken as the signed-in person, that the deal's timeline records who closed the job and why, and that the call is refused when the job is not open. These are meaningful behavioral and audit details not available 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?

The description is front-loaded and each sentence contributes needed information. The first sentence is somewhat long and clause-heavy, which slightly reduces readability.

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

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

For a mutation tool with no output schema, the description covers the important behavioral context: authentication identity, required rationale, audit trail, and refusal condition. The annotations already cover read/write, idempotency, openness, and destructiveness, 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%, so the baseline is 3, but the description adds useful meaning by specifying what the required 'reason' should convey: that Tommo proposes no more letters, review requests, or dates to contact the customer again. It does not add any syntax or format detail for deal_id beyond the schema.

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

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

The description states a specific verb ('End') and a precise named job ('After the project') on a deal, which lets an agent distinguish it from sibling tools such as close_the_job_that_gets_a_deal_paid. The scope is narrow and unambiguous.

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

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

It gives a clear precondition — the tool is refused when that job is not open — and describes the required rationale. However, it does not explicitly name an alternative tool or state when a different close-job tool should be preferred.

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

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

With annotations already declaring non-read-only, non-destructive, non-idempotent behavior, the description adds meaningful context beyond them: who performs the action (the signed-in person), the refusal conditions, that the reason is recorded on the deal's timeline, and the side effect that another job opens. This is strong disclosure for a mutation tool.

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

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

The purpose is front-loaded in the first clause and every subsequent sentence carries actionable information (recording, refusals, branching effect). The phrasing is dense and slightly convoluted with the guillemet-quoted job names, but nothing is padding.

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

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

For a mutation tool with no output schema and full parameter coverage, the description covers actor, preconditions, refusal cases, side effects and the flag-dependent branch. It stops just short of stating whether the call can be retried or reversed, which is minor given the annotations.

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 beyond the schema: it explains that reason is recorded on the deal's timeline and that the_work_is_finished alters both the refusal rule and the resulting job that opens. That goes past restating the parameter descriptions.

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

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

The description names a specific verb (End) and a named resource (Tommo Closer's job «Get the deal paid» on a deal), so the agent knows exactly what is being terminated. It also clarifies the branch where the job «After the project» is opened instead, which distinguishes this action from its outcome-sibling, though it never explicitly names close_the_job_after_the_project as the alternative 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?

Preconditions are stated ('Refused for a deal on which that job is not open') and the semantics of the_work_is_finished are given ('refused while an invoice of the deal is not paid'). However, there is no explicit guidance telling the agent when to choose this tool over close_the_job_after_the_project, leaving the caller to infer the relationship.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so safety and repeat-behavior are covered structurally. The description adds meaningful context the annotations cannot: the result is a non-public draft until publish, and template copy is rendered in the workspace's own name.

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

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

Draft status and the publish/update routing are front-loaded, and the template definitions are packed into one dense sentence. It is long but nearly every clause adds distinguishing information, with only mild redundancy between the template list and the enum.

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

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

There is no output schema, and the description implies but never states what is returned (e.g. a form id needed to later publish or update). Otherwise it covers creation semantics, template behavior, and the lifecycle handoff adequately for a 2-parameter tool.

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

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

Schema coverage is only 50% (the template enum has no description), so the description carries the burden and does so well, explaining exactly what each of lead/demo/quote/newsletter produces. This meaningfully exceeds what the raw enum conveys.

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 ('Make a Smart Form') and immediately scopes it as a draft, which cleanly distinguishes it from publish_a_form and update_form. It also enumerates the template variants by name, so an agent can match intent 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 says nothing is public until publish_a_form and routes field/word edits to update_form, giving clear context and two named alternatives. It does not spell out a 'when not to use' case (e.g. use duplicate_a_form to copy an existing form), 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 non-read-only, non-destructive, non-idempotent, open-world behavior. The description usefully adds that the event is created with default hours and booking window and is published immediately, which is real behavioral context, but it omits any warning that repeated calls (idempotentHint=false) create duplicates, and says nothing about permissions.

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

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

Two short, front-loaded sentences that get to the resource definition and creation behavior quickly. The second sentence about duration is slightly redundant with the parameter name, so it is not perfectly lean.

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

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

For a two-parameter create tool with annotations covering the safety profile and no output schema, the description covers purpose, defaults, and immediate publication adequately. It still leaves gaps around the name parameter and duplicate-creation risk, so it is only minimally sufficient.

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

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

Schema description coverage is 0%, so the description must carry both parameters. It addresses duration ('in minutes') only, which is largely redundant with the parameter name duration_minutes, and never explains the name parameter or that neither is required per the schema. One of two params is left entirely undocumented.

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 ('make an event type') and even defines what the resource is ('a meeting a lead may book'), which is more than the title gives. However, it does not distinguish itself from the many event siblings (save_an_event, publish_an_event, list_events, switch_tommo_work_on_an_event), so an agent must still infer which of these to pick.

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

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

The phrase 'published at once' implicitly contrasts with publish_an_event, suggesting this tool skips a separate publish step, but that alternative is never named and no explicit when-to-use/when-not guidance is given. Usage is only implied.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the description's job is to add state-change detail — and it does: the pipeline is usable at once and is seeded with the default pipeline's stages (New, Won, Lost). It does not mention permissions, return payload, or duplicate-name handling.

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 behavioral fact (usable immediately, default stages) front-loaded and a routing pointer appended. No filler, 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?

For a one-parameter create tool with no output schema, the essentials are present: what is created, that it is immediately usable, and its initial stages. The only real gap is the semantics of the 'name' parameter, which neither the schema nor the description documents.

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 0% for the single required 'name' parameter, and the description never mentions it at all — no naming rules, uniqueness constraints, or format. The description compensates with behavioral context (default stages) but adds nothing about the parameter it takes.

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 ('Make a pipeline') and immediately describes what the created object looks like. It also names the pipeline sibling it is not (save_a_pipeline) for stage edits, so an agent can distinguish create vs. modify without opening a schema.

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

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

The description implies when this is used (you need a new pipeline, usable immediately) and points to save_a_pipeline for changing stages. It does not state prerequisites, exclusivity, or when-not to use it versus other creation siblings, so guidance is implied rather than explicit.

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

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

Annotations cover safety (readOnly false, destructive false, idempotent false), so the description adds behavioral context: primary_email must be valid and unique across contacts, creation triggers a lead job, and the change is attributed to the caller. However, the lead-job phrasing ('opens the lead's Work a new lead job at birth') is cryptic and may confuse rather than clarify.

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, with purpose and key constraint front-loaded. The second sentence is awkward and unclear, but overall the definition is compact and avoids repetition. Some phrasing ('at birth', 'as the contact page does') adds noise.

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 a 4-parameter create tool with zero schema descriptions and no output schema, the definition is incomplete. It omits optional fields entirely and does not describe return values or permissions. The side-effect disclosure is helpful but insufficient to fill the gaps.

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

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

Schema coverage is 0%, so the description carries full burden. It clarifies primary_email as required, valid, and unique, but says nothing about phone, company, or full_name. Three of four parameters remain undocumented, leaving a significant gap.

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

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

The description states a specific verb and resource: 'Create a contact.' It also references parity with the contact page UI, which reinforces the purpose. The resource 'contact' clearly distinguishes it from sibling create tools like create_deal or create_a_form.

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

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

No explicit when-to-use guidance or alternatives are provided. It implies the tool is for creating contacts, but doesn't say when to choose it over restore_contact, update_contact, or other contact-related siblings. The phrase 'as the contact page does' hints at UI parity but is not a usage rule.

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. The description adds real behavioral facts beyond them: won/lost stages are rejected, the deal is placed in the resolved stage's pipeline, pipeline_id must match that pipeline, and title/currency defaults. It stops short of describing the returned handle or side effects like stage counters.

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?

Extremely dense but front-loaded: the create action and its stage constraint come first, defaults last. No filler sentences, every clause carries a constraint or a default.

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

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

For a 6-param write tool with no output schema and no schema descriptions, the definition covers defaults, eligibility rules, and cross-parameter consistency. Missing only the return value (deal id?) and any rate/permission notes, which are minor for this shape.

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 0% across 6 params, so the description carries the load and largely does: it explains stage_id resolution, the pipeline_id consistency constraint, and defaults for title ('New deal') and currency (USD). amount is never characterized (units, sign, optionality), which is the one remaining gap.

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

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

States a specific verb+resource ('Open a deal for a contact') and immediately scopes it to open stages, which distinguishes it from create_pipeline, create_contact, and the update_deal/move_deal siblings. An agent knows exactly what object is created without opening the schema.

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

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

Gives a concrete prerequisite ('resolve stage_id with list_stages') and an explicit refusal condition ('a won or lost stage is refused'), which routes the agent correctly. It does not compare against close siblings like update_deal or move_deal, but the create-vs-update distinction is implied by 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?

Beyond the annotations, the description discloses substantial behavior: no credential required, data stays in the workspace, no charge until the owner confirms the letter, one workspace per domain, throwaway mail domains refused, and what the returned API key represents. The two-phase lifecycle (owner confirms then signs in, agent acts as them) is exactly the kind of context annotations cannot express, and nothing contradicts readOnlyHint=false or idempotentHint=false.

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 action is front-loaded in the first sentence and most subsequent sentences carry real constraints. A few sentences are dense and awkwardly constructed ('The API key answered here, once, is for an agent with no person behind it'), which slightly slows parsing, but there is little pure filler.

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

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

For a five-parameter creation tool with annotations but no output schema, the description covers prerequisites, refusal conditions, billing, and the post-creation handoff to the owner. It leaves the response payload unstated, which is a modest gap given no output schema exists to carry that information.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including the 'tommo' enum and its trial semantics. The description adds contextual meaning (owner must be human, on the company's own domain; agent_name becomes the key's name) but no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The opening sentence gives a specific verb and resource ('Open a Tommos workspace for a company, with a human owner'), so an agent immediately knows what is produced and for whom. It implicitly separates the human-owner path from the credentialless/agent-only path, but never names a sibling tool for contrast, so it stops short of full differentiation.

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

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

Usage is implied rather than stated: the prerequisites ('One workspace per company domain; a public or throwaway mail domain is refused') and 'Needs no credential' tell the agent when the call will succeed or be rejected. There is no explicit 'use this instead of X' routing against any of the many sibling tools, so guidance remains inferential.

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 safety is partly covered, but the description adds real behavioral detail the annotations cannot: the embed renders nothing afterward and existing leads remain attached to their records. It stops short of stating whether the deletion is reversible or what happens to form submission history, so it is not a 5.

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

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

Two tight sentences, with the permanence and the lead-retention reassurance front-loaded before the parameter note. The final 'Pass the form's id or slug' sentence duplicates the schema and is the only wasted line, keeping this just under a 5.

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

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

For a single-parameter destructive tool with no output schema and annotations already covering the safety profile, the description supplies the two things an agent most needs: permanence and the effect on the embed and on leads. Reversibility and any post-delete response are unaddressed, so it is complete enough but not exhaustive.

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 already documented as 'Form id or slug'. The description's 'Pass the form's id or slug' restates the schema rather than adding accepted formats, lookup behavior, or error conditions, so it meets the baseline without exceeding 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?

States a specific verb and resource ('Delete a form') and immediately scopes it as permanent ('for good'), which separates it from siblings like update_form, duplicate_a_form, and get_a_form. It also pins the semantics to the familiar forms-list Delete, so an agent knows exactly which operation this mirrors.

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

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

The description conveys what this delete does versus the UI action and rules out the fear that deleting a form loses leads, which is genuine usage context. However, it never names alternatives or states when to prefer this over update_form, duplicate_a_form, or leaving the form published, so the guidance is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and non-idempotency, so the safety profile is covered. The description adds genuinely new behavior beyond them: the deletion cascades to child stages and is gated by three invariants. It stops short of saying whether deletion is hard or soft, or what error surfaces when a guard trips.

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

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

Two sentences with zero filler; the action and its cascade come first, then the refusal conditions. Every clause carries information an agent needs.

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

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

For a destructive, single-parameter tool with no output schema, the description covers the essential facts: what is destroyed, what is destroyed alongside it, and when the call is illegal. Remaining gaps (failure behavior, required permissions, reversibility) are minor for a tool of this size.

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 only one parameter and schema description coverage is 100% ('The pipeline's id (from list_pipelines)'), so the schema already carries the semantics. The description adds no format or sourcing detail beyond it, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Delete a pipeline') and adds non-obvious scope: the cascade to 'its stages'. This clearly separates it from create_a_pipeline and save_a_pipeline in the sibling list, and an agent knows exactly what entity is affected.

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 enumerates three situations where the call must not be made ('Never the only pipeline, nor the default one, nor one that still holds open deals'), which is strong when-not guidance. It does not, however, point to an alternative workflow (e.g. reassigning deals or changing the default first), so the agent is told what blocks it but not how to proceed.

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 still adds real behavioral value beyond them: the deletion cascades to all child pages, and it discloses the response ('how many pages left the book') for a tool with no output schema. Authorization requirements for the delete are not mentioned.

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

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

Two tight sentences, front-loaded with the cascade behavior and followed by the result. The 'as the contents' Delete does' clause is a useful UI analogy; 'the tommos stop reading them' is quirky brand jargon but short and does convey the effect.

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

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

With no output schema, disclosing the return value is the right call, and the cascade warning covers the main hazard. What an agent still cannot learn here is whether the `id` is a page id vs. a book id, or what permissions the delete requires.

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 (`id`) at 0% schema description coverage, so the description should compensate but never mentions it. The meaning of `id` as the page identifier is trivially inferable from the tool name, which keeps this at minimum-viable rather than lower.

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

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

States a specific verb and resource (delete a playbook page) and adds crucial scope: the cascade removes every descendant page. That scope distinguishes it from move_a_playbook_page, read_a_playbook_page, and write_a_playbook_page, though the siblings' names already carry most of the differentiation.

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

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

Usage is implied by the verb, and the cascade warning tells the agent the consequence of invoking it. However, there is no explicit when-to-use / when-not guidance and no pointer to alternatives (e.g. move or write) if the intent is to preserve the subtree.

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, so safety is covered, and the description adds genuinely new context: this is a soft delete, related history/bookings/deals survive, and permanent erasure happens after 30 days. It does not say whether a repeat call on an already-deleted id errors, which matters given idempotentHint=false.

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

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

One front-loaded sentence with the destructive action first and the retention nuance in a tight parenthetical. Every clause earns its place and nothing is padded.

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

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

There is no output schema, and for a one-parameter delete the description supplies the key lifecycle facts (soft delete, 30-day retention, what survives). It omits auth requirements and the repeat-call/idempotency behavior, minor gaps given the annotations cover destructiveness.

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 as a row uuid, so the schema does the heavy lifting. The description only restates 'by id' and adds no syntax or format detail beyond it — the baseline 3 applies.

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

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

States a specific verb+resource ('Delete a contact by id') and even narrows the scope with the soft-delete parenthetical. It is clearly distinguishable from create_contact, get_contact and update_contact by verb alone, though it never acknowledges the restore_contact sibling that an agent may actually need.

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 deletion is recoverable ('until it is erased for good, 30 days later'), which hints an undo path exists, but it never names restore_contact or states when deletion is the right action versus that alternative. No prerequisites or 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 flag destructiveHint=true, but the description adds genuinely new behavior: the delete is soft, history persists, erasure is final at 30 days, and recovery is possible via the deals screen. This is exactly the extra context an agent needs and cannot infer from the annotation.

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 action first and the retention nuance in parentheses; no wasted words.

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

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

For a one-parameter mutation with no output schema and annotations already declaring the destructive profile, the description supplies the one missing piece (soft-delete semantics and 30-day recovery window). Nothing needed to call it correctly is absent.

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

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

Only one parameter ('id') with 100% schema coverage, so the schema already documents its type and format (uuid). The description adds no syntax or format detail beyond 'by 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 and resource ('Delete a deal by id') and parenthetically clarifies the scope of deletion (soft, recoverable within 30 days). This distinguishes it from a hard-delete reading and gestures at restore_a_deal, though it does not name 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?

It conveys when the action is reversible ('the deals screen can bring it back until then'), which is useful context, but gives no explicit when-to-use vs alternatives guidance, e.g. that restore_a_deal is the counterpart to undo it.

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

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

Annotations declare a non-read, non-destructive, non-idempotent write with no open-world access, and the description adds real context beyond that: the original is not altered, the copy lands as an unpublished draft under a new link, and it is auto-named «(copy)». It stops short of saying what is returned (e.g. the new form's id/link) or any permission requirements.

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

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

One dense sentence with the verb and resulting artifact front-loaded, plus a short imperative for the input. Every clause (what is copied, naming, unpublished state) earns its place, though the run-on list is slightly hard to parse.

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

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

For a one-parameter mutation with no output schema and full annotation coverage, the description covers what is created and its state, which is enough for an agent to call it correctly. The only real gap is whether the response exposes the new form's id/link, which the agent would need for follow-up calls like publish_a_form.

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 documents 'Form id or slug'. The sentence 'Pass the form's id or slug' merely restates the schema, adding no format, validation, or lookup behavior. Baseline 3 is appropriate when the schema carries the full load.

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

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

States a specific verb+resource ('Copy a form as a new draft') and enumerates exactly what is copied (fields, words and settings) and the resulting state (new link, named «(copy)», unpublished). This cleanly separates it from siblings like create_a_form, update_form, and get_form without needing schema inspection.

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 anchors usage by referencing 'as the forms list's Duplicate does', which implies it is for replicating an existing form rather than authoring a new one, and it names the required input. However, it never states when-not to use it (e.g. use create_a_form to start from scratch) or any prerequisite such as the target form needing to exist or be accessible.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real content-level disclosure: no secrets are included, and library files are referenced by name rather than copied, plus the README documents what was omitted and why. It stops short of stating cost, size, or whether the archive is delivered synchronously.

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

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

Two dense sentences, front-loaded with what the tool produces, followed by the security and access constraints. Every clause carries a distinct fact; nothing is padding.

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

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

With no parameters and no output schema, the description carries the load by describing the return artifact in detail (zip, per-table JSON, README of exclusions) and the ownership restriction. An agent has enough to call it correctly and set expectations.

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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate at the argument level.

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

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

States a specific verb (export) and resource (the whole workspace), then details the artifact: one zip with one JSON file per table plus a README. No sibling offers exporting, so there is no confusion with any other tool in the list.

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

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

The only guidance is the eligibility gate 'For the owner only.' There is no alternative export/snapshot tool to route against, so no when-not-to-use statement is needed, but the description never says when exporting is appropriate versus reading the workspace state through read_the_workspace_state.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: visitors see what was last published (not the draft), and that the code can hold the form's height via keeps_its_room, with the form measured in its editor.

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 output-focused information is front-loaded, and the two clauses about keeps_its_room and measured_at are relevant because no output schema exists. It is dense with em-dashes but each clause carries meaning; only mild trimming is possible.

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

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

With no output schema, the description usefully explains return semantics (published-vs-draft visibility, height retention, measurement timing) that the agent could not otherwise know. It is nearly complete for a single-param read tool, though it never states the code's format (script tag vs iframe).

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 (form, id or slug) with 100% schema description coverage, so the schema already documents it. The description adds no syntax or format detail for the identifier, matching the baseline 3 for high-coverage schemas.

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 identifies a specific resource — the embed code shown on a form's Embed tab — which distinguishes it from sibling get_form (form data) and list_forms. However, it is phrased as a noun phrase describing the output ('The code to paste into a page...') rather than stating a retrieval action, so the verb is left implicit.

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

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

There is no when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The description is entirely output-oriented, so an agent must infer that it should be called when the embed code is needed rather than get_form.

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 adds a real behavioral fact beyond them: archived contacts are excluded by default and require include_deleted:true to be returned. It stops short of saying what happens on a missing id.

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

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

Two tight sentences, zero filler, with the core action front-loaded before the parameter tip. Every clause earns its place.

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

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

For a two-parameter read with no output schema, the definition covers purpose and the non-obvious parameter. Minor omission: no note on error/empty behavior when the id does not resolve.

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

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

Schema coverage is only 50% — id is documented but include_deleted is bare. The description compensates by explaining exactly what include_deleted:true does and why an agent would set it, adding meaning the schema lacks.

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

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

States a specific verb ('Fetch') and a singular resource ('a single contact by id'), which cleanly separates it from the list_contacts, search_contacts and get_contact_activity siblings. An agent can pick it without opening the schema.

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

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

It supplies a genuine when-to-use condition for include_deleted ('to resolve an archived contact, e.g. one a booking still references'), but offers no guidance on choosing this over list_contacts, search_contacts or get_contact_activity. Usage is implied rather than routed.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description nonetheless adds real context by disclosing ordering (newest first), row composition (source_table/source_id), and that long metadata values are truncated excerpts.

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

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

Two tight sentences with no waste: the resource and ordering constraint are front-loaded, and the second sentence earns its place by defining the row shape and the truncation behavior.

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

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

With no output schema, the description takes on the return-shape burden and does so (rows indexing a document, newest-first, excerpt truncation). Annotations cover safety, so the only omission is pagination behavior beyond the limit parameter.

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

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

Schema description coverage is 100% for both parameters (contact_id uuid, limit default 50 max 500), so the schema does the heavy lifting. The description adds no meaning about contact_id or limit beyond that, making the baseline 3 appropriate.

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

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

States a specific verb+resource: the activity timeline for a contact, with ordering ('newest first'). It is distinguishable from get_contact (the record itself) and list_contacts by the 'what happened' framing, but it never explicitly names a sibling as the alternative.

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?

'An index of what happened' implies the browsing/history use case, so intent is inferrable, but there is no explicit when-to-use guidance and no mention of when to prefer get_contact or search_contacts instead. Adequate but with a clear gap.

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

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

The annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered by structured data. The description adds nothing beyond that — no note on auth requirements, behavior for an unknown id, or what the fetched deal includes.

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, front-loaded with the verb and resource, with no filler. It is arguably under-specified rather than verbose, but there is no wasted text.

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

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

With one fully documented parameter and annotations covering the safety profile, the core call contract is complete. However, there is no output schema and the description says nothing about the returned deal shape or failure behavior, leaving an agent unable to predict the response.

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

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

Schema description coverage is 100% with a single required 'id' parameter whose uuid format is documented in the schema. The description's 'by id' reiterates rather than extends 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 (Fetch) and resource (a single deal) and constrains scope to one record by id, so it reads clearly. It does not, however, explicitly distinguish itself from the many sibling read tools such as read_the_money_of_a_deal, get_contact, or list_deals, so an agent must infer the boundary.

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

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

There is no when-to-use statement, no mention of prerequisites, and no named alternative. 'By id' weakly implies you must already hold a deal id, but nothing tells the agent when to prefer this over list_deals or the other deal-related reads.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real value by disclosing the depth and scope of what is returned (post-submit config, notification/confirmation emails, captcha, deal creation), which the annotations cannot convey.

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

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

A single front-loaded sentence with the operation first and the enumerated payload after the colon; no filler sentences and nothing repeated from the 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 no output schema, the description usefully compensates by naming the returned configuration areas, and annotations cover the safety profile. It stops short of noting whether field identifiers needed for a follow-up update_form are included, a minor gap.

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

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

Schema description coverage is 100% with a single documented parameter ('Form id or slug'), so the schema already carries the semantics. The description echoes 'by id or slug' without adding format, casing, or error behavior beyond the schema — baseline 3.

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

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

States a specific verb and resource ('Read one Smart Form's full configuration by id or slug') and then enumerates the exact contents returned (fields, copy, post-submit behavior, emails, captcha, deal creation, is_active). An agent can separate it from list_forms (plural listing) and update_form (mutation) without opening a schema.

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

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

Usage is implied by 'Read one ... by id or slug', which signals the single-record lookup case, but there is no explicit when-to-use versus list_forms, nor any stated prerequisite (e.g. needing a form id from list_forms first). Adequate but with a clear gap.

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

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

Annotations cover the safety profile (not read-only, open-world, non-idempotent, non-destructive), and the description adds genuinely new behavior: the invitation email originates from the workspace, names the inviter, owner can never be granted, and an admin cannot grant beyond admin. It omits what happens on a duplicate invite or what permissions the caller needs.

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

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

Two tight sentences with the action front-loaded and the privilege constraints compactly stated. Slightly awkward phrasing around "at a role" but no wasted content.

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

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

For a simple 2-param mutation with no output schema, the description covers purpose and privilege limits adequately, but leaves gaps on caller authorization, duplicate-invite behavior, and whether an invitation identifier is returned.

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 0% and there are 2 required params, so the description must carry the load. It clarifies that email is the person's address and constrains the role semantics (owner excluded, admin ceiling), but the role values themselves are already in the enum and no format/validation detail for email is given.

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 ("Invite a person to this workspace") plus the mechanism (email address) and the role enumeration. It is clearly distinguishable from siblings like change_a_members_role or remove_a_member, though it never names them 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 tool's purpose implies when to use it, and the role-cap rules hint at its boundaries, but there is no explicit guidance on when this is preferred over change_a_members_role, nor any stated prerequisites (who may invite whom). Usage has to be inferred.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world traits, so the bar is lower. The description adds real value beyond them: the exact return object shape and the auth-conditional rule that bookings/deals appear only if the caller may read those resources, plus the fact that bookings inline their contact.

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?

Extremely dense and front-loaded: purpose first, then return shape, then permission and nesting caveats. No sentence is wasted.

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

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

No output schema exists, and the description compensates by enumerating the returned fields; it also flags the permission-dependent inclusion of bookings/deals and the inlined contact. An agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning the schema does not: the half-open interval notation [from, to) clarifies that 'from' is inclusive and 'to' is exclusive, which affects how the window is queried.

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

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

States a specific verb and resource set: a period report covering contacts, bookings, and deals created in [from, to), with the 'one-call' framing distinguishing it from the list_contacts/list_bookings/list_deals siblings. It does not name those siblings explicitly, so it stops short of a full 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 'one-call period report' phrasing implies this replaces multiple list calls, but there is no explicit when-to-use/when-not statement against list_contacts, list_bookings, or list_deals. Usage must be inferred from the scope description.

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 ten-minute expiry, the person-scoped constraint ('for the signed-in person only'), and an explicit non-capability note ('this tool holds no Google access itself'). It also clarifies the downstream consequence of the connection (read for free times, written with bookings), which is exactly the behavioral context annotations cannot convey.

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

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

Front-loaded with what the tool returns, then layered with the essential constraints in a single tight sentence. It is dense with semicolons but every clause earns its place; a small loss for one long compound sentence rather than clearly separated points.

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-only tool with no output schema, the description supplies everything needed: what it returns, how long the link lasts, who it is valid for, and that the tool itself has no Google access. Nothing required to call and correctly interpret it 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing in the schema for the description to expand on. Mentioning that the link is scoped to the signed-in person usefully explains the implicit subject of the call.

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

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

States a specific verb and resource: it returns the link a person opens to connect their Google calendar to this workspace. The scope ('their Google calendar to this workspace') distinguishes it from the mailbox and Tommo Google-account siblings, though it never names those alternatives explicitly so the agent must infer the routing from names.

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

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

Usage is implied by 'the link a person opens in their browser to connect their Google calendar', giving clear context for when this applies. But it never states when NOT to use it or names the near-identical siblings (link_to_connect_a_tommos_google_account, link_to_connect_your_mailbox), leaving the agent to infer the choice.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description usefully adds the 10-minute link lifetime and an explicit non-capability note ('this tool holds no Google access itself'). It does not describe what happens on repeated calls or whether a prior link is invalidated, but the added TTL and auth-scope context is real value beyond the structured fields.

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

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

Three short sentences, front-loaded with the core purpose, then the parameter instruction, then the TTL/capability caveat. The parenthetical 'where it keeps the papers of the work' is slight flavor but does clarify what 'Drive' means in this product's world.

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?

Read-only, one parameter, no output schema, so the description needs to convey the return value implicitly — 'the link a person opens in their browser' does that adequately, and the 10-minute expiry closes the main open question. Slightly more on what the caller should do with the returned link would make it 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?

With 100% schema coverage and a single parameter, baseline is 3-4; the description adds meaningful provenance by telling the agent the slug comes from list_tommos, which the schema's terse 'The tommo's slug' does not.

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

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

States a specific verb+resource ('The link a person opens in their browser to connect a tommo's own Google account') and scopes what is being connected (Drive and mailbox). An agent can immediately distinguish it from the sibling link_to_connect_a_calendar and link_to_connect_your_mailbox.

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 the prerequisite for the only parameter ('Name the tommo by its slug (from list_tommos)'), routing the agent to the right lookup tool. It implies the context (connecting a tommo's Google account) but never states when-not to use it or how it relates to the calendar/mailbox connect-link siblings.

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

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

Goes well beyond annotations: link expiry of ten minutes, single-person scope, that the tool itself holds no Google access and connects nothing, what Tommo does with the mail (reads 30 days, sends as them), and the calendar side-effect for admin/owner unless unticked. Annotations only cover read-only/idempotent safety; this text explains the actual behavior and side effects.

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

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

Dense but front-loaded with the core answer (the link and what opening it does); subsequent sentences add necessary caveats. Slightly long for a single-purpose field, but each sentence carries non-redundant 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?

Complete for a zero-parameter link-getter: it states scope, duration, side effects, and the alternative tool, and there is no output schema to describe. Nothing an agent needs in order to call it or to route correctly is missing.

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

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

Zero parameters, so baseline is 4. The description correctly indicates no input is needed and clarifies that the identity comes from the signed-in session, which is useful context for a parameterless tool.

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

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

States a specific verb and resource ('the link ... to connect their own mailbox') and distinguishes from siblings by naming add_a_mailbox as the alternative for delegated Workspace accounts, as well as distinguishing from link_to_connect_a_calendar and link_to_connect_a_tommos_google_account by scope ('their own mailbox', 'that person only').

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

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

Explains the situation (signed-in person connecting their own mailbox by Google sign-in) and names an alternative path via add_a_mailbox for domain-wide delegation. It does not give explicit when-not-to-use guidance or a step-by-step flow, but the routing signal 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond them: it enumerates the returned fields including the enumerated state values (active, revoked, expired) and gives a security guarantee ("Never a secret"). It stops short of describing ordering or pagination.

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

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

One tight sentence, front-loaded with the verb and resource, followed by the field list and the security caveat. No filler and nothing important 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?

No output schema exists, so the description must carry the return-value burden, and it does by listing every meaningful field plus the secret-omission guarantee. An agent needs nothing further to call this correctly.

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

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

Zero parameters, so the schema imposes no semantic burden and baseline is 4. The description correctly does not pad with parameter talk.

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

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

States a specific verb (List) and resource (this workspace's API keys) and enumerates the returned properties: name, shown prefix, scopes, state with the three possible values, last use and expiry. An agent can immediately distinguish it from siblings make_an_api_key and revoke_an_api_key.

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 statement, and no alternatives named. Usage is only implied by the workspace scoping and read-only framing, which an agent can infer but the description does not spell out.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavioral meaning: a form from a blocked sender creates nothing and an inbound letter is not treated as a lead, which is information the agent cannot get from the schema or annotations.

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

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

A single tightly packed sentence that front-loads the resource ('the addresses this workspace has blocked'). The metaphorical diction ('knocked', 'letter') costs a little precision but the sentence wastes no space.

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 and no output schema, the description carries the burden of conveying the return contents, and it does name the per-entry fields (why, when, how many times). The remaining gap is that the figurative phrasing leaves return-field naming informal, but an agent has enough to call and interpret 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?

The tool takes zero parameters, so the baseline is 4. The schema is a closed empty object and nothing in the description contradicts that.

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 (listing the addresses the workspace has blocked) and even sketches what each entry contains. It does not explicitly distinguish itself from siblings like block_a_sender or unblock_a_sender, but the read-of-current-blocklist purpose is unambiguous.

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

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

Nothing says when to call this rather than block_a_sender or unblock_a_sender, and no prerequisites or exclusions are given. The description explains what a blocked sender means, which hints at context, but it offers no actual usage routing.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the description's job is to add context — and it does: default sort order (newest first), the inlined contacts shape, and pagination defaults (limit 50, max 500, offset). It does not say whether a total count is returned, but against a full annotation set this is solid added 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?

A single dense sentence that front-loads the resource and ordering, then covers the inlined shape, filtering, and pagination with no wasted words.

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

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

For a four-parameter list tool with no output schema, the description covers ordering, result shape (inlined contact), filtering, and pagination adequately. Only minor gaps remain, such as whether a total count or next-page indicator accompanies results.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including the ISO timestamp examples and defaults. The description largely restates those defaults and the ISO format, adding little beyond the schema, which matches the baseline 3 for a well-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 ('List bookings') plus meaningful qualifiers: sort order ('newest first') and the inlined invitee contact shape. The resource is distinct from siblings like list_contacts and list_events, though it never explicitly contrasts itself with them.

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

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

Usage is implied through the filtering and pagination instructions, which tell an agent how to narrow and page results, but there is no explicit statement of when to reach for this tool versus alternates, nor any prerequisites or 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 the safe read-only, idempotent, closed-world profile, so the safety bar is met structurally. The description goes further by disclosing the returned shape ('each field's id, name, type and choices'), which is genuine added value given there is no output schema. It stops short of noting pagination or ordering guarantees.

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

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

A single sentence, front-loaded with the action and resource, with the trailing clause earning its place by linking the output to the two consumer tools. No filler.

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

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

With no output schema, the description carries the burden of describing returns and does so adequately (id, name, type, choices). For a zero-parameter read of workspace configuration it is essentially complete; only minor omissions like ordering or permission requirements remain.

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

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

The tool takes zero parameters, so the baseline is 4 with nothing for the description to clarify. The schema's additionalProperties: false is consistent with the description's claim of an unfiltered workspace-wide listing.

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

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

States a specific verb and resource (list the workspace's contact fields) and immediately scopes it ('the workspace's own fields'), then ties the output to the sibling tools that consume those ids (update_contact, get_contact). An agent can distinguish this from list_contacts or get_contact 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?

Usage is clearly implied: call this to discover the field ids that update_contact accepts and that get_contact results are keyed by. There is no competing sibling tool offering the same listing, so explicit when-not guidance is less critical, but no exclusions or prerequisites (e.g., auth level) are stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds real behavior: ordering, pagination bounds, and the meaning of returned fields like is_test ('acts on nothing outward') and paused_at ('outreach paused'). That is substantive context beyond the structured fields.

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

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

Purpose is front-loaded in the first clause, then filtering, pagination, and return fields follow in a logical order with no filler. The pagination sentence duplicates the schema's default/max wording almost verbatim, a minor redundancy that keeps it from a 5.

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

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

With no output schema, the description correctly takes on the burden of describing returned rows (lead_status, utm_*, attributes, etc.), which is exactly what an agent needs. It stops short of telling the agent how to detect the end of pagination (no total count mentioned), a small gap for a list endpoint.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning over the schema: it frames created_after/created_before as the way to answer 'leads in a period' and groups the params by task (filter / paginate). The limit/offset and include_deleted wording largely restates the schema, keeping this below a 5.

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

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

States a specific verb and resource (list contacts) plus the default ordering (newest first), which immediately tells the agent what it gets back. It is clear but never differentiates itself from the prominent sibling search_contacts, so an agent still has to infer which one to pick.

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 offers usage context for the filters ('for leads in a period') and explains include_deleted, but that is parameter-level guidance rather than tool-selection guidance. It never states when to use this tool instead of search_contacts or get_contact, leaving the actual routing 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 establish read-only, idempotent, non-destructive behavior, so the description isn't carrying the safety burden. It still adds real value: the default sort order, pagination defaults and hard max, and the semantics of returned fields (client_name is the end client when the contact is a finder, plus lost_reason) — behavioral context the annotations cannot express.

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

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

Four tight clauses, front-loaded with what the tool returns and the sort order, then filtering, then pagination, then row semantics. 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?

With no output schema, the description usefully characterizes the returned rows (client_name, lost_reason), and it covers filtering, sorting, and pagination constraints. Only the meaning of the two untyped ID filters is left unresolved, which is a minor gap.

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

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

Schema coverage is 67% and the schema already documents limit, offset, and the ISO format for created_after/before; the description largely restates these. stage_id and pipeline_id are listed but neither the schema nor the description explains what values they accept, so the description doesn't compensate for the gap.

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

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

States a concrete verb+resource ('List deals') and adds the ordering ('newest first'), so an agent knows exactly what it gets back. It does not differentiate itself from siblings like get_deal or list_pipelines, but as the canonical deal-listing tool the intent is unambiguous.

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

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

Usage is implied through the filter and pagination clauses, which tell the agent how to narrow and page results, but there is no explicit when-to-use vs. when-to-use-an-alternative guidance and no mention of get_deal/search_contacts as differing options.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds domain context (what an event type represents) but says nothing about pagination behavior, defaults, or organizational scoping beyond 'in this organization', which the schema's limit field does not cover.

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

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

A single front-loaded sentence with the resource named first and the clarifying parenthetical immediately after. Zero wasted words.

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

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

For a read-only, single-optional-parameter list tool with no output schema, the description covers scope adequately. Only minor gaps remain, such as return shape expectations or whether results are paginated.

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

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

Schema description coverage is 100% with a single optional 'limit' parameter fully documented (default 50, max 500). The description adds no parameter meaning, so the baseline 3 for schema-documented params 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 clear verb ('List') and resource ('event types'), and the parenthetical 'the meetings a lead may book' disambiguates the domain term. It does not explicitly contrast with nearby siblings such as list_bookings or create_an_event, so it falls short of a 5.

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

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

There is no statement of when to use this tool versus alternatives like list_bookings, read_a_meeting, or create_an_event, and no prerequisites or exclusions. Usage is only inferable from the read-only listing verb.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds useful context about which fields each form record carries, but says nothing about pagination or return shape.

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

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

A single sentence that front-loads the scope ('in this organization') and the returned attributes. The phrasing around the «Tommo work» switch and agent_enabled/agent_job is slightly convoluted but every clause carries information.

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

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

For a simple read-only list tool with no output schema and only one well-documented parameter, the description is largely adequate, but it omits return ordering/pagination behavior and any hint about how many forms to expect, leaving minor gaps.

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

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

There is one optional parameter (limit) with 100% schema description coverage, so the schema already explains the default of 50 and max of 500. The description adds no syntax or semantics beyond what the schema provides; 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 ('List') and resource ('Smart Forms') scoped to 'this organization', and names the attributes returned (published, agent_enabled, agent_job). It is clearly distinguishable from get_form/create_a_form by verb, though it never explicitly contrasts 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?

Usage is only implied by the verb 'List'; there is no statement of when to prefer this over get_form, get_a_forms_embed_code, or the other list_* siblings, and no prerequisites or 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 readOnly, idempotent and non-destructive, so safety is covered; the description adds ordering (newest first) and the shape of each returned record, which the annotations do not. It does not mention pagination or default limits.

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

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

A single dense sentence with the resource description front-loaded, followed immediately by the routing hint. No wasted words.

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

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

With no output schema, the description usefully describes the return fields and ordering, which is the main gap it must fill. The only shortfall is the unexplained limit parameter, minor for a 2-parameter list tool.

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

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

Schema coverage is only 50% — limit is undocumented in both schema and description — and the description never mentions either parameter or how filtering by contact_id interacts with the pending-decision scope. It does not compensate for the coverage gap.

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

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

The description states a specific resource and scope — cards waiting for a person's decision — and enumerates the returned fields (id, lead/deal, kind, title, filing reason). It is clearly distinguishable from siblings like read_a_card or approve_a_card.

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

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

It tells the agent this is the queue of pending-decision cards and routes to read_a_card to open one, giving clear context for when to call it. It stops short of exclusions, e.g. whether done/closed cards are retrieved elsewhere.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds the returned fields (id, name) but says nothing about pagination, ordering, or permissions, appropriate but not rich.

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 resource, scope, and output fields, followed by a useful chaining hint. No wasted words.

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

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

With no input parameters and no output schema, the description usefully discloses the returned shape (id, name) and the natural follow-up call, which is what an agent needs. Slight gap: no indication of ordering or whether the list can be empty.

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

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

The tool takes zero parameters, so the schema carries no semantics to compensate for; baseline 4 applies. The description's mention of id/name refers to output, not input, so nothing is misleading.

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

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

States a specific verb (List) and resource (deal pipelines) scoped to the organization, and specifies the returned fields (id, name). It is distinguishable from write-oriented siblings like create_a_pipeline/delete_a_pipeline, though it stops short of explicitly naming what it is not.

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

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

Gives a concrete usage context: pair with list_stages to resolve a stage_id, which tells the agent this is a chaining/lookup step. No explicit exclusions or when-not-to-use conditions 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, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered structurally. The description adds genuine behavioral value by disclosing the shape of each returned item — every domain carries a proof flag and the DNS TXT record — which matters because there is no output 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?

A single tight sentence with no filler, and the two most decision-relevant details (proven status, TXT record) are placed at the end where they are easily scanned. It reads as a fragment rather than an actionable instruction, which costs it the top 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?

With no output schema, the description steps in to describe the return values, which is the most important gap to fill for a zero-parameter list tool, and annotations handle the safety profile. It is slightly thin on whether unproven or merely pending domains are included, but an agent can call it correctly with what is here.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is no parameter syntax for the description to explain. The description correctly implies no input is required to list the domains.

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 identifies the exact resource (the domains this workspace sends from) and the fields returned per item (proven status and the proving DNS TXT record), so an agent knows precisely what it gets. It never distinguishes itself from siblings like add_a_sending_domain, remove_a_sending_domain, or prove_a_sending_domain, and it is written as a noun phrase rather than a verb+resource statement.

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

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

There is no when-to-use guidance, no prerequisites, and no pointer to the closely related prove_a_sending_domain, add_a_sending_domain, or remove_a_sending_domain tools. The only hint that this is a read-only inventory view comes from the name and annotations, not the description text.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds value beyond that by disclosing the ordering guarantee and the full field set (position, kind taxonomy), though it doesn't cover pagination or behavior with no pipeline_id beyond what the schema says.

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

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

Two tight sentences, zero filler. The return-shape information is front-loaded and the action guidance follows immediately, each earning its place.

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

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

There is no output schema, so the description correctly supplies the returned field list and ordering, and it flags the tool's role as a prerequisite for stage-dependent writes. Nothing an agent needs to call this correctly is missing.

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

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

With a single optional parameter and 100% schema description coverage, the schema already documents pipeline_id as an optional narrowing filter. The description adds no syntax or semantics beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('List pipeline stages in order') and enumerates the returned fields (id, name, position, kind: open/won/lost), which clearly distinguishes it from the nearby list_pipelines and get_deal siblings. An agent knows exactly what it gets back.

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

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

Explicitly says to call this tool to resolve a stage_id before create_deal / move_deal and warns 'never guess it'. It names the dependent alternatives and the condition that triggers this call, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description goes beyond that by enumerating what each returned offer contains (text it applies to, before, after, why, supporting reasons with cards) — meaningful content context for a tool with no output 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?

The whole definition is a single sprawling run-on sentence stuffed with quoted fragments and neologisms, making it hard to parse and not front-loaded. The one operationally important clause ('The open ones by default; all: true...') is buried mid-stream rather than leading.

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

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

For a two-parameter, zero-required read tool with no output schema, the description adequately conveys what a returned offer looks like and the default filtering behavior. It is incomplete on the `limit` parameter and on pagination/ordering, which an agent would need to call it precisely.

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

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

Schema coverage is only 50%: `all` is documented in the schema and the description merely restates it, while `limit` is undefined in both the schema and the description. The agent is given no semantics at all for the limit parameter, so the description fails to compensate for the coverage gap.

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

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

The description names a specific resource — the text changes Tommo offered for this workspace's texts, with the underlying repeated-reason filter called out. It is distinguishable from the decision siblings (take/refuse) it alludes to. The idiosyncratic vocabulary («How it writes», 'Tommo', 'cards') makes the resource harder to pin down than it needs to be, but the core purpose is clear.

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 the default scope ('the open ones by default') and the flag that widens it ('all: true lists the decided ones too'), which is genuine routing guidance for the `all` param. However, it never names the sibling tools (take_a_text_change, refuse_a_text_change) an agent should use once it has identified an offer, so the when-to-use-vs-alternatives guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the shape and authority scope of the result set (id, name, address, role, with the four role values), which tells the agent what it can do with the output.

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 identifies the collection first and the payload second, with no filler. The 'as Settings → Team lists them' clause is slightly wordy but it does anchor the resource to a UI the agent may already know.

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

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

With no output schema and no parameters, the description carries the return-value burden and discharges it (fields plus the role enum). The only thin area is the absence of any dependency note on who may view the team, but as a safe read-only listing nothing essential is missing.

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

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

The tool takes no parameters, so per the rubric the baseline is 4. The schema coverage is 100% and there are no arguments whose meaning could be ambiguous.

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

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

States a specific verb (list) and resource (the workspace team), and enumerates what each entry contains: user id, name, address and role. It implicitly distinguishes itself from the adjacent list_contacts/search_contacts tools by scoping to 'people of this workspace', though it never names those siblings explicitly.

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

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

Usage is only implied by the resource it returns; there is no statement of when to prefer this over list_contacts or change_a_members_role, and no prerequisites or exclusions. For a zero-parameter read tool the implied usage is adequate, but the description does no routing work.

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 earns credit by disclosing the shape of the returned payload (switched-on state, jobs, triggers, deliverables, permitted acts), which matters because no output schema exists; it does not, however, mention result size, pagination, or whether inactive tommos are included.

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 no filler, front-loaded on the resource being listed. The nested parentheticals ("what starts each, what it delivers") and the trailing em-dash clause make it dense to parse, but 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?

For a zero-parameter read with no output schema, the description does the necessary work of outlining the return structure and the scope (this workspace, consistent with openWorldHint=false). It is slightly short of complete in that it never says how many tommos to expect or how to interpret a job's "acts" relative to read_an_act.

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 nothing for the description to disambiguate; baseline 4 applies. The description correctly conveys that the result is workspace-scoped and unfiltered.

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 resource (the tommos of this workspace) and enumerates exactly what each entry contains: on/off state, jobs with their triggers and deliverables, and each job's permitted acts. It is clearly a bulk read rather than a single-item read, which implicitly separates it from read_a_job and read_an_act, but it never names those siblings explicitly.

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

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

There is no guidance on when to reach for this tool versus read_a_job, read_an_act, or the switch_* tools that also touch tommos. No prerequisites, no scoping advice, no indication of cost or size of the result set. The agent must infer the use case entirely from the resource 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 non-readOnly, non-destructive, non-idempotent, so safety is covered. The description adds genuinely useful behaviour the annotations cannot carry: the secret is returned once and never stored, and writes on activities/settings/tommos scopes require an admin or owner. It stops short of describing what the response contains or whether the key can be re-fetched later.

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

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

Three short sentences, front-loaded with the purpose before the caveats. The phrasing ('answered once and kept nowhere') is slightly informal but carries meaning economically; nothing is redundant with the schema.

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

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

For a mutation tool with no output schema, the description covers the essential behaviour an agent needs: the one-time secret delivery and the permission gate on certain scopes. Missing only return-shape and expiry interaction detail, which is minor given the schema documents expires_in_days.

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 meaning beyond it: it flags a subset of write scopes (activities:write, settings:write, tommos:write) as admin-granted, information present nowhere in the enum or the individual property descriptions. This materially helps scope 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 and resource ('Make an API key') and narrows scope to the agent-with-no-person case, which cleanly separates it from list_api_keys and revoke_an_api_key in the sibling set. An agent can identify the operation without opening the schema.

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

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

Gives a clear condition for use ('for an agent with no person behind it, with only the scopes it needs') and a prerequisite for privileged write scopes (admin or owner). It does not explicitly name list_api_keys/revoke_an_api_key as the alternatives, so it stops short of full routing guidance.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, closed-world. The description adds genuine behavioral context beyond them: the mark persists regardless of later invoice-system state, the deal timeline records the signed-in person as the actor, and downstream automation ("the job that gets the deal paid") acts on it immediately. It is consistent with idempotentHint=true, though the phrasing is somewhat impressionistic.

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

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

Purpose is front-loaded in the opening clause, and each subsequent sentence carries information (durability, attribution, side effect, refusal). The phrasing is somewhat stylized and indirect ("the job that gets the deal paid looks at it now"), which slightly obscures the payload but wastes little.

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 mutation tool with no output schema, the definition supplies purpose, semantic nuance, side effects, attribution, and refusal conditions, while annotations cover the safety profile. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the sole parameter's origin is documented ("from read_the_money_of_a_deal"). The description adds no syntax or format detail beyond the schema, so the baseline of 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 ("Mark an invoice of a deal as paid") and disambiguates the write from the read sibling by describing the underlying scenario (a payment that reached the company outside its invoice system). It never explicitly contrasts itself with siblings like read_the_money_of_a_deal or close_the_job_that_gets_a_deal_paid, so full sibling differentiation is absent.

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 usage context (an out-of-band payment) and an explicit exclusion ("Refused for an invoice that was cancelled or never made"). It stops short of naming alternative tools for those excluded cases, so it is a clear context rather than a full when/when-not/alternatives routing.

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

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

Annotations already declare it is non-destructive, idempotent, and closed-world; the description adds genuinely new behavioral facts beyond those, namely that the entire subtree moves with the page and that a page can never be moved inside itself. It does not address permissions or failure modes, so it stops short of a 5.

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

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

A single dense sentence that front-loads the action and then defines the two optional parameters in order. Every clause carries information, though the nested parentheticals make it slightly harder to parse than it could be.

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

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

For a 3-parameter mutation tool with full annotation coverage and no output schema, the description supplies the key behavior an agent needs (subtree movement, root default, self-nesting prohibition). Only the id parameter's meaning is left implicit.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden and largely does: parent_id 'none' means the book root, quote index '0 the first' defines ordering among siblings, and id is understandably the page to move. The id parameter is only implicitly explained, keeping it from a 5.

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

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

States a specific verb (move) and resource (a Playbook page), scoped to relocation within the book, which cleanly distinguishes it from siblings like delete_a_playbook_page, add_playbook_pages, and write_a_playbook_page.

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

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

The description implies usage (reorganizing where a page sits in the book) and no sibling performs the same move, but it never explicitly states when to use this versus alternatives such as delete/re-add.

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

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

Goes beyond annotations by disclosing a real side effect (a move to won/lost withdraws the deal's open cards) and a failure mode (a lost move without a valid lost_reason is refused, naming the valid reasons). Annotations already cover safety/idempotency, so this added behavioral context is the description's real contribution.

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

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

Three tight sentences, front-loaded with the core action, then the prerequisite (list_stages), then conditional requirements and side effects. No wasted wording.

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

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

With no output schema, the description covers the mutation, its prerequisites, its refusal behavior, and its side effect, which is sufficient for correct invocation. A note on auth/permissions or the response shape would make it complete, but 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 coverage is 67%, and the description meaningfully extends the schema: lost_reason must be one of the organization's lost reasons, and stage_id is resolved via list_stages. This adds constraint semantics beyond the bare field definitions.

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 (move a deal to a stage) and adds the key relationship that the pipeline follows the stage, which helps disambiguate it from update_deal. It's clear on its own, though it doesn't explicitly contrast itself with the sibling update_deal or create_deal.

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

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

Routes the agent to list_stages to resolve stage_id and implies read_the_lost_reasons for valid lost reasons. It states the condition (move to lost stage) under which lost_reason is mandatory, but doesn't spell out when to prefer this over update_deal.

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

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

Annotations only cover the safety profile (idempotent, non-destructive, not read-only). The description adds real behavioral substance beyond them: it explains exactly what stops ('Nothing more is written to them — an approved letter included') and what does NOT change (lead status). This is meaningful effect disclosure, though it omits auth/rate-limit context.

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

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

Three tight sentences, front-loaded with the core action. The 'one stop Tommo obeys' phrasing is slightly idiosyncratic but compactly conveys that this is a hard block; every sentence contributes.

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

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

For a 2-param mutation with an annotation set and no output schema, the description is nearly complete: it covers the purpose, the effect, the status invariant, and the one undocumented parameter. Missing only explicit routing to resume_outreach and any return/confirmation detail.

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

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

Schema coverage is 50% — contact_id is documented in-schema but note is not. The description compensates by explaining the note param ('note says until when or why'), which is the only gap in the schema, so it adds genuine meaning over what the schema provides.

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

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

States a specific verb (pause) and resource (outreach to a lead) in the first clause, clearly distinct from the sibling resume_outreach. An agent can immediately tell this is a suppression action on a contact's outreach.

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 (stop outreach until resumed) and gives guidance for the note param ('until when or why'), but never states explicit when-to-use/when-not or names resume_outreach as the counterpart for the reverse condition. Usage is inferable 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?

Beyond the annotations, the description discloses the 150,000-character read limit, that the workspace's model spend is consumed, and that nothing is persisted ('Nothing is written'). These are meaningful behavioral facts (cost, limits, no side effects on data) that the annotations alone don't 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 core action is front-loaded in the first clause and the rest strings supporting details in one dense paragraph with minimal waste. It is a bit packed, but every sentence earns its place.

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

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

With no output schema, the description still explains what is produced (proposed pages of facts placed among the book's pages) and the cost/limits of the call. It is complete enough for an agent to invoke correctly, though the shape of the proposal result could be clearer.

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 0%, so the description carries the burden and covers all three params: text is the document body with a char cap, hint describes what the document is, and place_under accepts a page id, 'root', or empty to auto-place. This compensates well for the absent schema descriptions, though it doesn't specify formats like how page ids look.

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+resource - reading one company document and proposing Playbook pages - and explicitly contrasts with add_playbook_pages ('Nothing is written: add the pages you keep with add_playbook_pages'). An agent can distinguish this from the sibling write tool without opening either schema.

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

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

It states the operating context clearly ('as the Playbook's Import does') and routes the agent to add_playbook_pages for the follow-up write step. What's missing is guidance on when NOT to use this versus other document-reading tools, but the key propose-vs-write decision is explicit.

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

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

Adds genuine behavioral context beyond the annotations: the up-to-one-hour DNS propagation latency and the race-condition note that another actor may have already proven the domain. Consistent with readOnlyHint=false (it does mutate proof state) and idempotentHint=true (re-running is safe). No contradiction.

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

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

Front-loaded with the action, then the two outcome branches, then the latency caveat. Compact and every sentence carries information, no padding.

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

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

With no output schema, the description usefully explains both result branches (proven, or reports what was searched) and the propagation timing. Complete enough for a one-parameter verification tool, lacking only explicit routing versus sibling domain tools.

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

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

Schema coverage is 100% and the single id parameter is already documented as coming from list_sending_domains. The description adds no format or sourcing 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: it looks up the domain's DNS TXT record to verify/prove the sending domain. Clear what the tool does, though it never names or contrasts with sibling tools like add_a_sending_domain or list_sending_domains that share the domain workflow.

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

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

Usage is implied by "now" and the found/not-found framing (run after adding a domain), but there is no explicit when-to-use statement, no prerequisites, and no named alternative. The agent must infer placement in the workflow.

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

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

With annotations already covering mutation safety, idempotency, and open-world scope, the description adds useful behavioral detail: publishing makes current form content visible until the next publish, and unpublishing hides the embed. It does not cover permissions or failure behavior, but the core state effect is clear.

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

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

Three tight sentences front-load the action and outcome, pair the boolean branches symmetrically, and end with the required argument. Every sentence carries weight with no filler.

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

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

For a simple two-parameter mutation tool with annotations and no output schema, the description explains the state change and visitor-visible effect well enough for correct invocation. Minor missing elements such as permission requirements or error behavior are not critical here.

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

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

Schema coverage is 50% because form is documented while published lacks a schema description, so the description compensates by defining the semantics of both true and false for the published flag. It also repeats the accepted form identifier, though it adds no format detail beyond id or slug.

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 (publish/unpublish a form) and explains the visitor-facing effect, clearly distinguishing it from generic form siblings like create_a_form, update_form, and delete_a_form. An agent can identify it as the visibility-state tool without opening the schema.

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

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

The description explains what published: true and published: false do, but it does not explicitly say when to choose this tool over update_form or other form siblings, nor does it list prerequisites or exclusions. Usage is inferable from the operation, but no alternative routing is provided.

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=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: it discloses the observable effect of unpublishing (the public booking page stops responding), which the annotations cannot convey. It stops short of saying whether the change is instantly live or requires a separate save.

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, and the value mapping is front-loaded so an agent gets the operating instruction immediately. The trailing clause about the booking page is appended efficiently rather than padding. Minor awkwardness in the phrasing of the false branch, but nothing wasted.

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

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

For a 2-parameter, required-only, no-output-schema mutation tool with annotations already covering idempotency and safety, the description is close to sufficient: it names both polarities and the user-visible effect. Remaining gaps (whether an event must pre-exist, whether a save is required) are 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?

Schema coverage is 50%: 'event' is documented in the schema (id from list_events) but 'published' has no schema description. The description compensates directly by defining true=publish and false=take down, which is exactly the missing semantics. Slightly below 5 because it doesn't restate or reinforce the event-id lookup path.

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

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

The description states a specific verb+resource and, unusually, encodes both polarities of the operation: 'Publish an event (published: true) or take it down (false)'. This lets an agent understand the toggle without opening the schema. It does not, however, differentiate from close siblings like save_an_event or create_an_event, which is the only thing keeping it from a 5.

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

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

The description supplies the consequence of the false state ('its public booking page answers nothing'), which implicitly motivates when to use each polarity. But it never states prerequisites, when to prefer this over save_an_event/create_an_event, or whether the change must be saved afterward. Usage is implied rather than guided.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds an inventory of returned content but no additional behavioral traits such as pagination, auth requirements, or performance characteristics, so it sits at the annotated baseline.

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, which is good, but it is a rambling run-on with awkward phrasing ('who decided it and when where the record holds that') and poetic filler ('a letter's exact subject and body, an invitation'). Some content earns its place, some is padding.

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

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

With no output schema, the description does carry the burden of describing returns and makes an attempt by listing field groups, which is useful. However, the grammatical clutter makes it ambiguous what is actually returned, and it never grounds what a 'card' is in this domain, leaving the definition only minimally adequate for a read tool.

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

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

Schema description coverage is 100% and the single card_id parameter is fully documented in the schema (with a pointer to list_open_cards). The description adds no further meaning to the parameter, so the baseline of 3 for high-coverage schemas applies.

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

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

The description states a clear verb+resource combination (read one card in full) and enumerates the card's contents: kind, status, decider, reason, and steps. It is much more specific than a bare 'read' but stops short of explicitly differentiating itself from siblings like list_open_cards or approve_a_card, leaving the single-vs-list distinction to be inferred.

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

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

There is no when-to-use guidance, no prerequisite, and no named alternative. The only routing hint ('from list_open_cards') lives in the schema, not the description, so an agent gets no help here about when to pick this over list_open_cards or read_an_act.

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 lowered. The description adds real behavioral value beyond them, notably the own_goal flag distinguishing workspace-authored versus system-authored goal text, and the meaning of autonomy_threshold as cards filed before autonomous sending.

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 opening with the core resource, with no filler. It is dense with nested parentheticals ('the workspace's own words, or ours when it wrote none — own_goal says which'), which slightly burdens reading but every clause carries information.

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

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

With no output schema, the description must convey the return shape, and it does: goal plus own_goal flag, autonomy_threshold, and acts with their words and settings. For a two-param read tool with full annotations, nothing essential is missing.

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

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

Schema coverage is 100% – both slugs are documented and told to come from list_tommos. The description adds no syntax or constraint detail beyond that, so the schema carries the load and 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 resource ('one job of a tommo') and enumerates exactly what it returns: the goal, the autonomy_threshold cards, and each act with words and settings. This separates it from list-oriented siblings, though it never names which sibling to use instead.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The only routing hint is implicit: the schema's 'from list_tommos' tells the agent where the slugs come from, and calling out 'each of its acts' faintly implies reading a whole job rather than one act. That is not stated guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and non-open-world. The description adds value beyond that by disclosing the content shape of the returned record, including that the transcript is 'as stored' and the join detail includes the source sentence. No pagination or edge-case notes, so not a 5.

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

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

A single, front-loaded sentence with no filler, packing the return contents and the id guidance efficiently. Slightly dense with a parenthetical, but every clause earns its place.

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

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

There is no output schema, but the description compensates by enumerating the returned fields, and the read-only annotations cover the safety profile. Adequate for an agent to call correctly, though it could note behavior when the id is unknown or not found.

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 0% schema description coverage, the description must carry parameter meaning. It does define what the single id represents (a meeting's source_id from get_contact_activity), which is essential context a bare 'meeting_id' string does not convey. It omits format examples, keeping it from a 5.

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

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

States a specific verb (read) and resource (one meeting), then enumerates exactly what is returned: title/time, summary, stored transcript, invitees, and lead-join status. This clearly distinguishes it from siblings like read_a_paper, read_an_act, or read_a_card.

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 directs the agent to identify the meeting by id and specifies the id's origin ('a meeting row's source_id from get_contact_activity'), which is actionable routing guidance. It stops short of explicit when-not-to-use or alternative-tool comparisons, so not a 5.

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