MightyAutomation

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

Annotations already declare not-read-only, non-destructive, and closed-world, so the safety profile is covered. The description adds what the annotations cannot: the note is appended (additive), appears on the contact's timeline, and is visible in the CRM to members. It does not mention permissions or how existing timeline entries are affected, which a mutation tool could 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?

One front-loaded sentence: the action and target come first, followed by visibility and use cases. No filler and no repetition of the title or schema.

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

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

With an output schema, annotations, and full parameter coverage, the description only needs to convey intent and effect; it does both by naming the timeline and its audience. Minor gaps remain on required permissions and how notes interact with existing timeline entries.

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%: the contact_id and content parameters are fully documented in the schema, including that content is plain text up to a few paragraphs. The description adds no parameter detail beyond that, 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?

Specific verb and resource: 'Append a note to a contact's timeline.' It is clearly distinct from add_tag, update_contact, and send_email because it describes a timeline note rather than a tag, a field update, or an email. An agent can route to this tool without opening another schema.

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

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

The description gives intended use cases (handoffs, call summaries, member-visible context), which implies when to call it, but it never states when not to call it or names an alternative such as update_contact for structured data or add_tag for labeling.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true; the description earns credit by disclosing the merge semantics ('existing tags are kept') that explain why the operation is non-destructive. It stops short of covering permissions or failure behavior, but with annotations present that is a minor gap.

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

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

Two short sentences, both front-loaded with the mutation semantics first and contact-location second. No filler or redundancy.

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

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

With rich annotations, a fully described 3-parameter schema, and an output schema, the description covers everything an agent needs: what is merged, what is preserved, and how the contact is identified.

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 tags, email, and contact_id in detail. The description restates the either/or locating rule but adds no syntax, limits, or format information beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Merge one or more tags onto a contact') and adds the distinguishing scope detail that existing tags are kept, which separates it from an update/replace operation like update_contact. An agent knows exactly what the call does without opening the schema.

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

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

Gives clear operational context: locate the contact by contact_id or email, and tags are merged rather than replaced. It does not name explicit alternatives or when-not conditions (e.g., how to remove or overwrite tags), which keeps it 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 this is a non-read-only, non-destructive, open-world creation tool. The description adds useful behavioral context that the link is shareable with anyone and can bind bookings to a contact record, but it does not mention permissions, workspace constraints, or what happens when the link expires.

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 written sentences with zero filler. The core purpose is front-loaded, and the optional contact-binding behavior follows immediately.

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

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

An output schema exists, so return values need not be described. For an eight-parameter creation tool, the description gives enough conceptual context to call it correctly, though it could do slightly more to explain prerequisite workspace/calendar assumptions.

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

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

Schema description coverage is 100%, so the schema fully documents all eight parameters including defaults, bounds, formats, and enum values. The description only explains the optional contact binding, which the schema already covers, so it does not add meaning beyond the structured field documentation.

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

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

States a specific verb (Generate) and resource (shareable scheduling link) with the key scope: the booker can reserve time on the workspace calendar, optionally tied to a contact. No sibling creates booking links, so it is distinguishable from the surrounding contact/automation tools.

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

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

The description implies when to use it — when you need a shareable scheduling link, optionally bound to a contact — but gives no explicit exclusions, prerequisites, or comparison to alternatives such as add_note or list_appointments.

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 openWorldHint=true, so the safety profile is covered. The description adds real behavioral value by explaining the push model — events are POSTed as they happen — and that delivery goes to an external https endpoint. It doesn't mention retry behavior, delivery failure handling, hook-count limits, or whether duplicate subscriptions are allowed.

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

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

Three compact sentences: what it does, how to pick an event_type, and why you'd choose this over polling. The core action is front-loaded and 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?

With an output schema present, return values needn't be described, and the description covers purpose, delivery model, and event-type guidance adequately for a 2-parameter tool. The remaining gap is lifecycle context — how to inspect or remove existing hooks (list_hooks/delete_hook) and any subscription limits.

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 would be 3, but the description earns more by enumerating concrete event types (contact_created, form_submitted, appointment_booked) and the '*' wildcard, which gives the agent real syntax guidance the schema's generic string does not. Target URL semantics are left to the schema's uri format.

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

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

States a specific verb and resource ('Register a webhook URL') and immediately explains the effect ('MightyAutomation POSTs each matching event to it as they happen'). This clearly distinguishes it from list_events and from sibling mutation tools like add_tag or create_booking_link.

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 use event_type '*' for every event and names the alternative pattern ('instead of polling list_events'), giving the agent a clear decision rule. It stops short of stating exclusions, such as when not to register a hook or how this relates to delete_hook / list_hooks.

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 and idempotentHint, so the safety profile is covered. The description adds real context beyond that: the concrete consequence ("Events stop being delivered to that URL") and the precise semantics of the idempotency (deleting a missing hook still succeeds). It does not mention confirmation requirements or reversibility, which would be needed for a 5.

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

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

Three short sentences, zero filler, with the destructive effect and idempotency stated up front rather than buried. Every sentence carries distinct information.

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

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

A single-parameter mutation tool with full annotation coverage and an output schema needs only what is here: what it removes, the side effect, and the idempotency contract. 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 schema already states the id is a uuid from list_hooks, so the description's parenthetical adds nothing new. With the schema doing all the work, 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?

"Remove a webhook subscription by id" states a specific verb and resource, and the parenthetical routing to list_hooks separates it cleanly from create_hook and list_hooks. An agent can identify the tool's job 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 tells the agent where the id comes from (list_hooks), which is the main prerequisite for correct invocation. It stops short of explicit when-not-to-use guidance or a stated alternative, so it falls just below the top band.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and closed-world scope, so the agent knows this is a non-destructive write. The description adds nothing beyond that: it doesn't say what happens on duplicate enrollment, whether the call is idempotent, or that the contact begins receiving automated emails/messages as a side effect — the key behavioral consequence of a mutation like this.

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, and the two required lookups are surfaced before any detail. Slightly dense with the parenthetical qualifier, but nothing is wasted.

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

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

An output schema exists so return values need not be explained, and all parameters are documented. What's missing for a mutation tool is behavioral completeness: preconditions on the contact, duplicate/already-enrolled behavior, and any permission or rate considerations.

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

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

Schema description coverage is 100%, so all four parameters (including the id sources and the case-insensitive name match) are already documented in the schema; the description largely restates them. Baseline 3 applies — it adds no format, precedence, or conflict-resolution rules (e.g., what if both contact_id and email are supplied).

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: start/enroll a contact in an automation, with the two identifier paths spelled out. It references list_automations as the name source, which partly orients it among siblings, but never distinguishes itself from adjacent tools like upsert_contact or send_email for the 'contact may not exist yet' case.

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?

Operational context is decent: it names the id sources (automation_id or automation_name, contact_id or email) and where names come from. However there is no statement of prerequisites (must the contact already exist?), no when-not guidance, and no explicit alternative named for the 'create the contact first' scenario.

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 that this is a read-only, non-destructive, non-open-world operation, so the description's burden is lower. It adds useful behavioral context by noting the lookup is case-insensitive and returns the contact if it exists, though it does not discuss not-found handling or rate limits.

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

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

Three short sentences with no wasted text. The primary lookup behavior is front-loaded, followed by return behavior and the sibling alternative.

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 one-parameter lookup with a full output schema and annotations covering safety, the description supplies everything an agent needs: lookup key, case sensitivity, return semantics, and an alternative for broader searches.

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 single email parameter is fully described in the schema, so the baseline would be 3. The description adds semantic value by specifying that matching is case-insensitive, which is not captured in 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 and resource: 'Look up a CRM contact by email address.' It adds the unique lookup key and case-insensitive behavior, and names a sibling alternative for broader searches, so an agent can distinguish it from search_leads 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 clearly routes broader searches by name, company, stage, or phone to search_leads, which is an explicit alternative. However, it does not explicitly differentiate from get_contact or list_contacts, so the routing guidance is clear but not fully exhaustive.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and closed-world scope, so the safety profile is covered. The description adds genuinely new behavioral detail by disclosing that the response bundles recent activity and upcoming events, but says nothing about behavior for unknown ids or data volume.

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

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

Two short sentences, front-loaded with what you get, followed by how to obtain the id. The id-source list is duplicated verbatim from the schema, which is the only 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?

An output schema exists so return values needn't be explained, and the one required parameter is fully specified. The extra note about bundled activity/events plus id provenance is enough for an agent to call this correctly; only error behavior is unaddressed.

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

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

Schema coverage is 100% and the single parameter is already documented as a uuid with its sources, so the description's id-provenance sentence largely restates the schema. Baseline 3 applies; no additional format or validation semantics are contributed.

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 resource and states the payload precisely: 'Full contact record plus recent activity and upcoming events.' This differentiates it from the list/search siblings by promising a complete single-record view, 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?

The description gives a real prerequisite chain — obtain the id from find_contact, list_contacts, or search_leads — which is useful routing information. It stops short of saying when to prefer this over list_contacts/find_contact or what happens on an invalid/missing id, so usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description usefully discloses what the response includes (10 most recent ledger entries by category), but adds nothing about freshness, pagination, or what happens when the ledger is empty.

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

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

A single front-loaded sentence with no filler; the parenthetical listing entry types is efficient. The em-dash clause slightly dilutes the core statement but still 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 an output schema present the description needn't enumerate return fields, and it still summarizes them. For a parameterless read-only tool, the only missing element is any note on data staleness or scope limits, which is 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?

Zero parameters, so the baseline is 4. The description correctly implies a workspace-scoped, argument-free read and there is no parameter semantics to compensate for.

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 ('credit balance for this workspace') and adds the returned payload composition (last 10 ledger entries: grants, purchases, spend). It is unambiguous and clearly distinct from the CRM-ish siblings, though it does not name a contrasting sibling because none exists.

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 trailing clause 'this is how you check what MCP calls and AI usage cost' implies the usage context (cost auditing), but there is no explicit when/when-not guidance or named alternative. Adequate but leaves the agent to infer the trigger conditions.

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

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

Annotations cover the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), and the description adds real behavioral detail: which types are rejected, the size cap, and a side effect (attaching an import note to a contact). It stops short of describing failure modes or what the returned asset looks like, but the output schema covers returns.

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

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

Two dense sentences with zero filler, and the primary action and destination are front-loaded ahead of the constraint list.

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 annotations and an output schema present, the description covers the key decision inputs (allowed types, size limit) and the optional side effect. Only deeper edge-case behavior (e.g., what happens on fetch failure) is unaddressed.

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

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

Schema coverage is 100%, so all three parameters are already documented. The description adds only marginal meaning for contact_id by explaining the note's content ('that the file was imported for them'); name and url semantics are left to the schema.

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

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

States a specific verb ('Download a remote file') plus the destination ('workspace Media Assets library'), making the effect unambiguous. No sibling tool overlaps this import capability, so differentiation is implicitly clean.

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

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

Gives concrete applicability constraints — public https only, allowed MIME types, 10 MB cap, and the optional contact-note attachment. It doesn't name an alternative tool, but no sibling does this operation, so the guidance is close to complete.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile needs no restating. The description adds the useful behavioral fact that results are scoped to 'upcoming' appointments by default, but says nothing about ordering, result horizon, or pagination 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?

Two short sentences, zero filler, with the result scope front-loaded before the parameter hint. 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?

An output schema exists and annotations cover safety, so the definition is minimally sufficient. However, for a listing tool the description never clarifies the default time horizon of 'upcoming', result ordering, or caps, and it does not position the tool against list_events.

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

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

Schema coverage is 100% and both parameters already carry ISO 8601 descriptions including the 'from' default of now. The description only reinforces that the pair is optional and bounds a window, adding little beyond the schema.

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

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

States a specific verb and resource ('Upcoming appointments on the workspace calendar') with a clear scope qualifier. It is clear enough to act on, but it does not distinguish itself from the sibling list_events, which an agent could plausibly confuse with appointments.

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 'upcoming' scoping and the optional window; there is no explicit statement of when to call this versus list_events or get_contact. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the returned field set and the enrollment linkage, but nothing beyond annotations and the output schema (e.g., pagination or ordering) is disclosed.

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

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

Two short clauses: the resource/fields come first, then the actionable follow-up hint. Zero waste and front-loaded.

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

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

With zero params, an output schema carrying the return structure, and annotations covering safety, the description is nearly complete for this simple list tool. The only minor gap is thin guidance on when to choose this versus other list_* 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?

There are zero parameters, so the baseline is 4. The description correctly implies no filtering inputs are needed, matching the empty schema, and adds no misleading parameter claims.

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 the resource (automations in the workspace) and enumerates the returned fields (id, name, status), making the tool's scope concrete. It also connects to the sibling enroll_automation, helping distinguish it, though the verb 'list' is only implied rather than stated in the description text.

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 hints at downstream usage ('use an automation id or name with enroll_automation'), which implies this tool is a lookup for enrollment. However, it never states when to prefer this over the other list_* siblings or any explicit conditions/exclusions, leaving usage only implicitly 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=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavior: results are ordered newest first. It says nothing about whether a total count is returned or how deep paging behaves, which would matter at scale.

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, sort order and paging model front-loaded, alternative tool named last. No filler or redundancy.

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

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

A read-only list tool with three fully documented optional parameters, an output schema that defines return values, and annotations covering the safety profile. The description supplies the one thing structured data cannot: sort order and sibling routing.

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 every parameter carries its own range, default, and format description, so the schema does the heavy lifting. The description only restates the limit/offset paging intent and created_after filtering, adding no format or edge-case detail beyond the schema.

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

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

States a specific verb and resource ('List CRM contacts') plus a behavioral trait (newest first) that no schema field conveys. It also names the sibling it is not, distinguishing it from search_leads without the agent needing to diff schemas.

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

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

Explicitly routes name/stage/tag-style searching to search_leads and states the two supported use modes (created_after filtering, limit/offset paging). It does not clarify its relationship to find_contact or get_contact, which are plausible confusions for a single-record lookup.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value beyond that by disclosing the sort order ('newest first') and the breadth of the feed ('and more' event types), neither of which is derivable 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?

Two tight sentences, with the resource and ordering front-loaded ahead of filter guidance. The second sentence largely restates schema-documented parameters, so it earns slightly less than full marks, but nothing is bloated.

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

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

An output schema and annotations are present, so return values and safety need not be re-explained. However, the description omits pagination behavior — a limit of 100 with a default of 25 implies more events exist, yet there's no mention of how to page past the cap, which is a real gap for an activity feed.

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 type, limit, and since including ranges and format; baseline 3 applies. The description's example event list is marginal added value and even introduces a naming mismatch ('entered_stage' vs schema's 'stage_changed'), which could confuse the agent about valid values.

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 resource and ordering: 'Workspace event feed, newest first', followed by an enumeration of the event types returned. This is clearly distinguishable from the list_* siblings (list_contacts, list_appointments, list_hooks), though it never explicitly names an 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?

It explains what the two filters do ('Use type to filter to one event type and since to filter by timestamp'), which implies when to apply them, but gives no guidance on when to call this versus get_contact or list_contacts, nor any exclusion or prerequisite.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds meaningful domain context by explaining that hooks are URLs receiving POSTed events. It does not discuss return volume, ordering, or whether webhook secrets are exposed, leaving some behavioral gaps.

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

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

Two short sentences, front-loaded with the resource definition and followed by the related-tool pointer. Every clause earns its place 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?

With an output schema present and annotations covering safety, the description does not need to explain return values. It supplies the domain meaning of a hook and the sibling tools used to manage hooks. A small gap remains in not explicitly stating the tool returns all subscriptions for the account.

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 and the schema is fully described, so there is nothing for the description to compensate for. Baseline 4 applies since no parameter semantics are needed.

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

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

The description defines the resource precisely: 'REST-hook subscriptions — the URLs MightyAutomation POSTs events to.' That is more informative than the name alone and distinguishes it from unrelated sibling list tools (contacts, automations, events) by domain. It stops short of stating the verb 'list,' which the tool name and title already supply.

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 'Pair with create_hook / delete_hook to manage them' does give useful context about the surrounding workflow. However, it never says when to call list_hooks versus those alternatives, nor does it state any preconditions. Usage 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 readOnlyHint=true, destructiveHint=false, openWorldHint=false, and an output schema covers the return shape. The description still adds the non-obvious behavioral fact that the result is ordered by board position, which no structured field conveys.

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 first says what is returned and how it is ordered, the second routes the agent to the dependent tools. Front-loaded and fully earned.

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, an output schema, and safety annotations, the only things an agent needs are what the data is, its ordering, and how to consume the exact strings — all present. Slightly short of total completeness only because it does not state that the list is fixed/static per workspace or what happens when no stages exist.

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 there is no parameter semantics to explain and the baseline of 4 applies. Nothing in the description misleads about inputs.

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

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

States the concrete resource returned (pipeline stage names) and its scope/ordering (board order), which is specific enough for an agent to know what comes back. It does not need a verb to be unambiguous, but it does not explicitly mark itself as the read-only enumerator relative to list_* siblings.

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

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

Gives an explicit downstream usage rule: use the exact names from this result when calling update_contact or search_leads. That is strong 'when to use' guidance tied to named tools; it lacks any 'when not to use' or prerequisite statement, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds that free text spans first/last name, email, and company, and that results come with a total. It says nothing extra about ordering, pagination interaction, or how the 200-row cap behaves when more matches exist.

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

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

A single front-loaded sentence that names the filters first and the return shape last, with no filler or repetition. Nothing could be removed without losing information.

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

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

With an output schema present, return-value detail is unnecessary, and all six parameters are documented at 100% coverage, so the description is functionally sufficient. The remaining gap is sibling disambiguation against list_contacts and find_contact, which matters given how crowded that namespace is.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates schema content — the free-text fields, the lifecycle enum values, and 'has a phone number' mirror the q, lifecycle, and has_phone descriptions verbatim, adding little interpretation beyond them.

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 (search) and resource (CRM contacts), and enumerates the three filter dimensions (free text, stage, lifecycle/phone presence) that define its behavior. It does not, however, distinguish itself from close siblings like list_contacts or find_contact, 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?

Usage is implied by the enumerated filters — you reach for this when filtering contacts by text, stage, lifecycle, or phone presence — but there is no explicit when-not or routing to find_contact/list_contacts. The prerequisite for valid stage names lives in the schema (list_pipeline_stages) rather than being reinforced here.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true; the description adds real value on top — it flags irreversibility ('this is a real outbound email'), the do-not-contact safety branch, and the timeline logging side effect. It does not mention rate limits, attachments, or queuing behavior.

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

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

Three short sentences, front-loaded with what it does, then safety behavior, then the confirmation caution. No filler.

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

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

With an output schema present and rich annotations, the description covers the essentials an agent needs: identity, side effects, safety failure mode, and the confirmation requirement. Minor gaps (attachments, delivery timing) are not blocking.

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

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

Schema description coverage is 100% and every parameter (contact_id, subject, body, cc, bcc) is documented in the schema, so the description adds no parameter-level detail beyond it. Baseline 3 applies.

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

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

Specific verb+resource ('Send an email to a contact') plus the sender identity and the side effect of logging on the contact timeline. This distinguishes it from timeline-only siblings like add_note and makes clear it is a real outbound send.

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

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

States a hard precondition ('Fails safely if the contact is marked do-not-contact') and a required pre-send step ('Confirm the subject/body with the member'). Clear context for when to use it, though no explicit alternatives are named.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false; the description adds the important PATCH semantics and the destructive-ish 'tags replaces the tag set' warning plus the add_tag workaround. It doesn't mention permission requirements or what happens to suppressed contacts, but the safety profile is well covered.

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: the core action and field list come first, the side-effect caveat and alternative come second. Nothing is redundant with the title or the schema.

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

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

With an output schema present and rich per-parameter descriptions, the description only needs to carry semantics and routing, and it does both. The one gap is that it doesn't clarify the boundary against upsert_contact for create-or-update flows.

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 89%, so the baseline is 3; the description earns extra by restating the non-obvious destructive semantics of 'tags' and offering add_tag as the merge path. The remaining fields are already documented per-parameter in the schema, so no further gain was possible.

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

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

Specific verb+resource ('Update fields on an existing contact') followed by an enumeration of the updatable fields (stage, lifecycle, email/phone/name, do_not_contact). The mention of add_tag as the merge alternative separates it from the tag sibling tools.

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

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

Explicitly routes tag-adding to add_tag rather than this tool, and the 'only fields you pass are changed' clause tells the agent this is a partial update. It never contrasts with upsert_contact, which is the most likely sibling to confuse this with.

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 description adds useful behavior beyond the annotations: tags are merged rather than replaced, notes are appended, and events are emitted so automations can fire. This complements the idempotent and non-destructive hints, though it doesn't mention what happens to omitted fields on update.

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

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

The description is two tightly written sentences with zero filler. It front-loads the core upsert behavior and follows with key operational details.

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

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

Given the rich schema, output schema, and annotations, the description covers the critical upsert semantics and side effects. It could be slightly more complete by stating whether omitted fields are preserved on update, but it is sufficient for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by identifying email as the upsert key and clarifying that tags merge and notes append, which goes beyond basic parameter documentation.

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

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

The description clearly states a specific verb and resource: create or update a CRM contact keyed by email. It captures the upsert behavior well, but it does not explicitly distinguish itself from the sibling update_contact or find_contact tools.

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

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

It gives clear usage context by framing the tool as the way to "save a lead" and noting that email is the only required field. It does not explicitly say when to prefer update_contact or find_contact, but the primary use case is unambiguous.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that it validates the connection and exposes key label/scope, but it does not describe failure behavior or any auth/rate-limit details.

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

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

One front-loaded sentence with no redundant restatement of the title. Every phrase contributes to purpose or return 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 zero-parameter, read-only connection check with an output schema and clear annotations, the description provides enough to call it correctly. Return-value details are covered by the output schema, so no further return explanation is required.

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

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

There are zero input parameters and schema coverage is 100%, so the schema fully carries input semantics. Per the rubric, a no-parameter tool starts at 4; the description does not need additional input details.

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 ('Validate') and concrete return set (workspace/project, key label, scope). It is distinguishable from all listed siblings, none of which is an identity or connection-check 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?

The opening clause 'Validate the connection' gives a clear usage context: call this to confirm credentials and identify the bound workspace. There are no sibling alternatives to disambiguate, but it does not state exclusions or a when-not condition.

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