DealMachine

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 value beyond that: it confirms free accounts are permitted, surfaces the specific response fields to inspect (plan.is_paid, balance), and warns about a false-positive activation signal — meaningful behavioral context for a gating read.

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 action, then conditional guidance, then a warning. Every sentence earns its place: what it reads, who can call it, when to call it, and the trap to avoid.

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 names the two fields that actually drive the decision (plan.is_paid, balance), which is sufficient for an agent to act. It does not enumerate other plan attributes a caller might see, a minor residual gap for a zero-parameter read.

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 mention of plan.is_paid and balance is output-side context rather than parameter documentation.

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

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

States a specific verb and resource: read the active plan and remaining data credits. The possessive 'your active plan' implicitly differentiates it from dealmachine_plans (catalog of plans) and dealmachine_usage, though neither 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 concrete trigger: after a Stripe payment, call this before retrying an approved enrichment, and check plan.is_paid plus balance. It also gives an explicit negative rule ('a checkout URL or the user saying they paid is not proof of activation'), though it never names dealmachine_checkout or dealmachine_plans as the alternatives.

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

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

The billing model ("Costs 1 property data credit per subject found") is genuinely useful context not derivable from the annotations, and it partly explains why destructiveHint is true for what looks like a search. It does not disclose return volume per subject or pagination, so it stops short of full behavioral coverage.

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 capability first, then cost, then optionality. Nothing is redundant and no sentence 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?

For a tool with nested objects, ~23 leaf parameters at 0% schema coverage, and no output schema, the description is too thin: it never says how many comps come back per subject, what the default timeframe/limit is, or what the response shape looks like. An agent would have to guess at defaults and result volume.

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 criteria object alone carries roughly twenty undocumented fields (tolerances, sort_by, include_active_listings, etc.) whose semantics and defaults the description does not supply. The only added meaning is that location and criteria are optional with defaults; the description does not explain what a "subject" versus a returned comp is or what the default limit is.

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: "Find comparable sales + active listings" and bounds the scope to "up to 25 subject properties." An agent can tell this is a comps lookup rather than a general search, though it never names the sibling it supersedes (e.g., dealmachine_property_search vs dealmachine_comps).

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?

"Location/criteria optional (sensible defaults)" tells the agent it may call with property_ids alone, which is real usage guidance, and the credit cost hints at a caution before bulk calls. But there is no when-to-use / when-not-to-use framing against the many other property tools, and no prerequisite or exclusion 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 destructiveHint=true and idempotentHint=false, so the safety profile is covered structurally. The description adds genuinely new operational context: the deletion cascades to all items, it is irreversible, it requires explicit confirmation, and writes are never auto-retried — behavior an agent cannot derive 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?

Four short sentences, front-loaded with the action and cascade consequence, then the approval gate and retry policy. 'Delete list. Delete a list and all its items.' is mildly redundant but the rest 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 destructive tool with no output schema, the description covers the essentials an agent needs: what is destroyed, irreversibility, the confirmation gate, and retry semantics. Only the relationship to sibling delete/patch tools on the same resource is left unstated.

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

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

Schema coverage is 50%: confirmed already carries a description ('Set true only after the user approves this change or credit use') and the description reinforces that gating requirement. However, the nested path/list_id structure is not elaborated in the description, so it adds only marginal meaning over the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Delete list') and immediately adds scope that matters: it deletes the list AND all its items. The cascade wording implicitly separates it from dealmachine_delete_lists_list_id_items, but the sibling is never named explicitly, so differentiation requires inference.

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 precondition for invocation: user approval must be obtained and confirmed=true set before the call. It stops short of naming alternatives (e.g., deleting individual items instead of the whole list) or stating when-not-to-use, so it is clear context without 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 destructiveHint=true and idempotentHint=false, so the safety bar is partly met; the description adds genuinely new behavior: an explicit user-approval gate with confirmed=true, the credit-use tie-in, and the fact that writes are never auto-retried. It stops short of describing partial-failure or batch semantics for up to 10,000 IDs.

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

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

Four short sentences, front-loaded with the action and then the constraints. No filler, though the redundant first two sentences restate the same removal action rather than adding 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 nested-body mutation with no output schema and low parameter coverage, the description covers approval and retry behavior but omits what a caller should expect on partial failures, whether removal is reversible, or how list_id relates to the returned state.

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 33%, and the two body fields carry no inline descriptions beyond the enum values. The description partially compensates by naming both ID kinds (property/person) and the confirmed flag, but it leaves the default id_type of internal_property_id and the 10,000-item cap unaddressed.

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 ('Remove items from list'), then narrows it to 'specific property or person IDs'. This cleanly separates it from dealmachine_delete_lists_list_id (which removes the list itself) and dealmachine_list_add_items.

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 precondition ('Requires user approval and confirmed=true') but never says when to choose this over list_add_items or the list-level delete, nor what conditions make removal appropriate. Usage context is implied rather than directed.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, so destruction is known. The description adds genuine context beyond them: approval gating before credit use, the non-deletability of designs in active campaigns, and the fact that writes are never auto-retried. It does not describe effects on recipients/campaigns or reversal, but it substantially supplements the annotations.

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

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

The critical approval constraint is buried behind a duplicated first sentence. 'Delete design. Delete a design.' is pure waste, and the useful content (campaign block, approval gate, no-retry notice) follows in a compressed stream without structure.

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 annotation coverage and no output schema, the definition covers the main agent risks: approval gating, credit use, the active-campaign restriction, and automatic retry behavior. Missing only the failure/error outcomes for a blocked delete or the state of the design afterwards, which are minor for this tool.

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

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

With 50% schema coverage, the description only restates that confirmed=true is required, which the schema already says, and says nothing about the nested path.id 'Resource ID' beyond what the schema provides. It adds no syntax, format, or meaning that the schema does not already convey, 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?

The verb+resource is technically present, but the opening two sentences ('Delete design. Delete a design.') are a verbatim restatement of the title and tool name, adding no information about which entity is deleted or its scope. It never mentions the mail-design concept or distinguishes the operation from the patch/get mail_designs siblings that share the resource.

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?

'Designs used in active campaigns cannot be deleted' is an explicit when-not condition, and 'Requires user approval and confirmed=true' is a stated prerequisite. No comparison to update/retrieve alternatives is offered, but the exclusion condition is clear and actionable.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered; the description adds real value beyond that with the default-address restriction, the user-approval requirement, and the 'writes are never retried automatically' caveat. It still doesn't say whether the deletion is recoverable or what happens to campaigns referencing the address.

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 substantive content (default-address rule, approval gate, no auto-retry) earns its place, but the first two sentences are near-duplicates of each other, wasting the most prominent position on a redundant 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 destructive delete with no output schema, the description covers the prerequisite, the human-approval protocol and retry behavior, which is nearly everything an agent needs to call it safely. The remaining gap is the post-deletion state (recoverability, effect on campaigns using the address).

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% and both parameters are already documented in the schema ('Resource ID', 'Set true only after the user approves this change or credit use'). The description restates the confirmed=true approval semantics but adds nothing about the id's format, where to obtain it, or nested-object shape — 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 ('Delete return address'), which cleanly separates it from the patch/post/deletion siblings in the mail_return_addresses family. However, the same sentence is immediately repeated, so the opening reads as filler rather than sharpened scope.

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 precondition ('the default return address cannot be deleted — set another as default first'), which implicitly routes the agent to post_mail_return_addresses_id_default, plus the approval/confirmed=true gate. It doesn't state when-not-to-use beyond the default case, or mention alternatives like reassigning rather than deleting, 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?

Goes well beyond destructiveHint=true: it discloses retention semantics (notes, files, activity kept; prospect re-addable), that mail always ends regardless of cascade, that cascade=false preserves memberships/opportunities, that user approval and confirmed=true are prerequisites, and that writes are never auto-retried. These are exactly the consequences an agent needs before a destructive call.

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

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

Front-loaded with the action and archiving behavior, then prerequisites. Slightly repetitive — 'end its mail' and later 'Mail always ends' say the same thing, costing one clause.

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, non-idempotent mutation with no output schema, it covers effect, reversibility, data retention, cascade option, approval gate, and retry policy. Nothing material is missing for correct invocation, aside from what a success response looks like, which is minor given no output schema.

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

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

Schema coverage is only 33% (the `cascade` query param has no schema description), and the description compensates by explaining precisely what cascade=false preserves. It also reinforces the `confirmed` approval gate already documented in the schema. Minor gap: it presents cascade as `?cascade=false` while the schema types it as a string, so an agent gets no guidance on accepted literal 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 specific verb and resource ('Remove prospect', 'Archive the prospect') and immediately clarifies that this is a reversible archive rather than a hard delete. That framing distinguishes it from the granular sibling deletes (files, notes, photos, tags) under the same prospect.

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 conditions: use this to remove/archive a prospect, pass `?cascade=false` to preserve list memberships and open opportunities, and the user must approve before calling. No explicit exclusions pointing at an alternative tool (e.g. update vs. remove), but the context is unambiguous enough for correct selection.

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 carried structurally. The description adds genuinely new behavioral context beyond them: a human-approval gate, the required confirmed=true flag, and that writes are never automatically retried. It does not say what happens if confirmed is omitted or what the response looks like, keeping it below a 5.

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

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

Three short sentences, front-loaded with the action, then the approval prerequisite, then the retry caveat. No filler or restatement of the name.

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

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

For a destructive single-resource delete with full annotation coverage and no output schema, the description covers the approval workflow and retry behavior, which is what an agent most needs. The vague reference to 'credit use' and the absence of failure-mode detail are minor remaining 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 50% and the nested path object (id, file_id) is documented only in the schema, not the description. The description does explain the semantics of confirmed as tied to user approval, which adds value, but it leaves the path parameters entirely 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 and resource ('Delete prospect file'), which is unambiguous against the delete siblings such as delete_prospects_id_photos_photo_id and delete_prospects_id_notes_note_id because the resource type differs. It does not explicitly contrast itself with those siblings, but the naming is precise enough to select the right 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 description states an invocation precondition (user approval and confirmed=true) but gives no guidance on when to choose this over sibling deletion tools or when to avoid it. Usage is implied by the resource name rather than explained.

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 partly covered. The description adds genuinely new behavior: an approval gate via confirmed=true, a mention of credit use, and the important operational fact that writes are never retried automatically — the latter is exactly the kind of context an agent cannot infer from the schema.

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

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

Three short sentences: the action first, then the safety gate, then the retry caveat. No filler, no restatement of the tool name, and the most decision-critical constraint (approval) is front-loaded.

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

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

For a two-parameter destructive tool with no output schema, the description covers the destructive nature, the approval requirement, and retry behavior. It doesn't state whether deletion is reversible or what happens to the parent prospect, but the essentials for safe invocation are present.

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 50% schema coverage, the nested path object's id and note_id are already documented inside the schema, and confirmed carries its own description. The description reinforces that confirmed must be true only after approval, which is a slight semantic addition beyond the schema wording, but it adds no format or example detail. Baseline 3 fits.

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 first sentence names a specific verb and resource ("Delete prospect note") that maps unambiguously to the note-level endpoint, distinguishing it from dealmachine_patch_prospects_id_notes_note_id and the GET variant. It stops short of explicitly contrasting with siblings, but the resource specificity is high enough that selection is easy.

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 precondition for invoking (user approval plus confirmed=true), which is meaningful usage guidance for a destructive tool. It does not say when to prefer editing a note over deleting one, or mention related operations, so usage context is implied rather than framed against alternatives.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so safety profile is covered. The description adds genuinely new behavior: a human-approval gate before credit use and the fact that writes are never auto-retried, which tells the agent not to blindly re-issue the call.

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 the action front-loaded and the approval/retry constraints immediately after. Minor boilerplate in "before changes or credit use" but nothing that wastes an agent's reading budget.

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 two-parameter delete with no output schema, the description covers the approval workflow and retry semantics. It leaves permanence/irreversibility of the photo deletion and post-delete return state implicit, which the destructiveHint partially absorbs.

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?

Top-level schema coverage is 50%, but every individual property (id, photo_id, confirmed) already has a description and example in the schema, so effective coverage is high. The description only echoes the confirmed=true requirement and does not explain the path identifiers, so it adds little beyond structured data.

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

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

States a specific verb and resource ("Delete prospect photo"), which cleanly separates it from the file, note, and tag deletion siblings. It does not explicitly name a sibling alternative, but the resource noun is unambiguous enough to route correctly.

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 precondition ("Requires user approval and confirmed=true") that tells the agent how to call it, but not when to choose it over alternatives such as listing photos first via dealmachine_get_prospects_id_photos or whether there is a soft-delete path. 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds genuinely new context beyond these: the requirement for user approval and confirmed=true, that credit may be consumed, and that writes are never automatically retried. It doesn't state behavior when the tag doesn't exist, but the approval/retry semantics are substantive additions.

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 the core action front-loaded and the gating/retry caveats following. No filler text.

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

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

For a destructive mutation with no output schema, the description covers the critical safety facts: approval gating, confirmed flag, and no auto-retry. Minor gaps remain around error behavior and whether the operation is reversible, but 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?

The schema already documents all three fields (id, tag_id, confirmed) despite the 50% coverage metric, and the description mostly restates the confirmed requirement rather than adding new meaning. It doesn't clarify whether confirmed gates only writes or also credit use, or what happens if confirmed is omitted.

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

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

The description opens with a specific verb and resource: 'Remove tag from prospect.' This distinguishes it from the sibling that adds a tag (dealmachine_post_prospects_id_tags_tag_id) and from bulk setters like prospect_tags_set, though it doesn't explicitly name those alternatives.

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 context is implied by 'Requires user approval and confirmed=true before changes,' which tells the agent a confirmation flow is needed. However, there is no explicit when-to-use guidance or routing to alternatives such as dealmachine_prospect_tags_set or dealmachine_get_prospects_id_tags.

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 destructiveHint, it discloses the concrete failure mode (409 while prospects still carry the tag), the cascade semantics of force, the human-approval precondition, and that writes are never auto-retried. This is exactly the context an annotations object 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?

Four short sentences, each adding a distinct fact, with the destructive/force behavior front-loaded. No filler.

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

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

A destructive nested-parameter tool with no output schema and no annotations beyond safety hints; the description covers failure modes, cascade risk, and approval. It omits any return shape or what happens on an unknown/missing tag ID, but the essential decision inputs are present.

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 33%, and the description compensates by explaining `force` as a cascading removal from every prospect before deletion and `confirmed` as the approval gate. The `path.id` parameter is covered only by the schema, so it isn't fully supplemented.

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

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

Opens with a specific verb+resource ("Delete tag. Delete a workspace tag.") that scopes the operation to workspace-level tags. It doesn't differentiate from the closely-named sibling dealmachine_delete_prospects_id_tags_tag_id, which removes a tag from a single prospect — an agent could confuse the two.

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 conditional rule for `force` and states the approval/confirmed gate, which is real usage guidance for the destructive path. But it never names an alternative tool or says when not to use this one (e.g. use the prospect-tag delete to detach from one prospect).

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 and idempotentHint=false, and the description adds genuinely new behavioral facts: an approval gate keyed to confirmed=true and the promise that writes are never auto-retried. It does not say whether the deletion is permanent, soft-delete, or what happens to related records, which keeps it below 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?

The safety information is front-loaded and the whole thing is short, but the redundant 'Delete task. Delete a task.' repetition wastes the opening sentence that should have carried the differentiating detail. Half the text is noise on a four-sentence description.

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, nested-object tool with no output schema, the description covers the approval/credit gate and retry policy but leaves out outcome information an agent needs: whether removal is permanent, what a success response looks like, and side effects on the parent record or associated tasks.

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 only 50%, but both parameters do carry descriptions ('Task ID' and the confirmed approval note). The description reinforces the meaning of confirmed=true but adds nothing about the nested path.id or any format constraints, so it roughly matches rather than compensates for 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 (delete a task), so an agent can tell it apart from dealmachine_patch_tasks_id or dealmachine_get_tasks_id as the destructive removal variant. The opening 'Delete task. Delete a task.' is pure duplication that adds no differentiating detail, but the underlying 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?

It states a prerequisite workflow (user approval, then confirmed=true) which effectively tells the agent when it is permitted to call. However, it never contrasts this with the sibling update tool (dealmachine_patch_tasks_id) or explains when deletion is preferable to updating, so the when-to-use-vs-alternatives dimension 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?

Beyond the destructiveHint/openWorldHint annotations, it discloses the cascade (delivery log removed), the external side effect ('nothing more is sent to the URL'), the human-approval gate tied to the confirmed flag, and the non-retry policy for writes. These are exactly the facts an agent needs before firing a destructive call.

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

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

Four short sentences, front-loaded with the action and its blast radius. Every sentence carries information, though 'or credit use' is a slightly confusing boilerplate fragment for a delete operation.

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

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

Covers destruction scope, approval requirements, and retry behavior for a destructive mutation with no output schema. It stops short of stating irreversibility or error behavior for a missing/already-deleted webhook, which an agent would plausibly need.

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

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

Schema coverage is 50% and both id and confirmed already carry their own descriptions, so the schema does most of the work. The description reinforces the confirmed gating semantics but says nothing about the required path/id object, leaving the nested-structure requirement to the schema alone.

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 webhook') and immediately clarifies scope by noting the delivery log is removed too. An agent can distinguish this from dealmachine_patch_webhooks_id or dealmachine_get_webhooks_id without consulting the schema.

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

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

The description gives a prerequisite ('Requires user approval and confirmed=true') but never says when to delete versus patch/disable a webhook, nor what happens on an unknown ID. Usage is implied by the verb rather than articulated against 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?

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description explains why: a matched property consumes one property credit and contacts consume people credits, with no charge on a miss. It also discloses the auth requirement (connected account with paid access) and that DNC flags accompany phone numbers — real 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?

Four tight sentences: purpose and input modes first, then output shape, then the contact gating rule, then cost and prerequisites. No filler, and the credit-cost warning is placed where an agent will see it before invoking.

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 credit-consuming, 7-parameter tool with no output schema and destructiveHint=true, the description covers auth, cost, no-match behavior, and what gets returned. The only gap is that it never explains the 'fields' filter or the relative cost of the owners_and_family/renters/residents audience values.

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 meaningful semantics for contact_audience, explaining that contacts are omitted unless it is set and that 'none' costs zero people credits, but it says nothing about the 'fields' array parameter that controls which property fields are returned.

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

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

The description opens with a specific verb and resource: 'Finds who owns a US property from its street address', and enumerates the accepted address input modes. That address-keyed framing implicitly separates it from siblings like dealmachine_enrich_apn and dealmachine_enrich_latlng, 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?

Usage conditions are implied rather than stated: a connected DealMachine account with paid access is required, and contacts only come back when contact_audience is set. Nothing tells the agent when to prefer this over the APN- or lat/lng-based enrichment siblings, so routing between them is left to inference.

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

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

Annotations already mark the tool as non-read-only/destructive, and the description goes further by disclosing paid-account requirements and per-property/per-contact credit costs, plus that returned phones carry DNC flags. It doesn't discuss rate limits or error behavior, so not a 5.

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

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

One dense paragraph front-loads purpose and batch limits, then layers cost and return details. Every sentence adds information, though the block could be split for faster scanning.

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

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

Covers return contents, account prerequisites, credit costs, and contact behavior, which is substantial for a 5-param tool without an output schema. It leaves out error/empty-result handling and how the fields array influences returned details.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by explaining that APN formatting is normalized automatically, that data batches share location/options, and how contact_audience governs contact inclusion.

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 ('Finds who owns') and resource ('Assessor's Parcel Number'), plus batch scope (one apn or up to 250 in data). This clearly differentiates it from siblings like enrich_address or enrich_latlng, which take other identifiers.

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

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

Provides operational context—batch limit, location narrowing, and that contacts are omitted unless contact_audience is set—but never says when to choose this tool over enrich_address or enrich_latlng. Usage is implied by the APN input rather than explicitly 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?

The annotations already flag the operation as non-read-only and destructive-ish, so the description's job is to explain the real side effect, which it does well: one people credit per matched person, one property credit per included property, and no charge on a miss. What is left unexplained is why destructiveHint is set on what reads as an enrichment lookup, and whether results are cached or metered on repeat calls.

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

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

Four short sentences, front-loaded with the primary action and input, then return shape, then prerequisites and cost. No sentence is redundant and none restates the title verbatim.

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?

Despite having no output schema and a nested location parameter, the description covers inputs, what the response contains, the optional property expansion, and the billing behavior. An agent has everything needed to decide to call it and to predict the charge.

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

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

Schema coverage is 100%, so all four parameters including the nested location object are documented structurally, which sets the baseline at 3. The description reinforces the email requirement and the credit consequence of include_properties, but adds nothing about the 'fields' whitelist or how location narrows a match.

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 ('looks up a person by email address'), names the required key, and enumerates what comes back (name, contact info, demographics, optional properties). Against siblings like dealmachine_enrich_name, dealmachine_enrich_phone, and dealmachine_enrich_address, the lookup key alone makes the distinction 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?

Gives clear operating context: a connected paid DealMachine account is required, and the cost model is spelled out per match. It does not explicitly route the agent away from sibling lookups when the identifier is a phone or name rather than an email, so the when-not 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?

Adds substantial behavior beyond the annotations: the 300-foot match radius, the requirement of a connected DealMachine account with paid access, the per-match property credit and per-contact people-credit cost model, and the fact that nothing is charged on a no-match. That credit-charging model is exactly the destructive consequence implied by destructiveHint=true, and it is disclosed explicitly rather than left to 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?

Four sentences, each carrying distinct information: what it matches, what it returns, the contact gating rule, and the preconditions/cost. Front-loaded with the core action and no filler.

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

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

There is no output schema, so the description correctly compensates by describing the return shape (property details, and owner contacts with DNC flags when requested). It covers prerequisites and cost but says nothing about match ambiguity, tie-breaking between multiple properties inside 300 feet, or the practical meaning of the fields array.

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 the schema already documents all four parameters, so the baseline is 3. The description earns a bump by explaining the behavioral effect of contact_audience (owners yields names/phones/emails; unset yields property-only) rather than just restating the enum 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 specific verb and resource (finds the property closest to a lat/lng and its owner) plus a concrete scope constraint: within 300 feet. The coordinate-based input inherently separates it from the address/APN/name/phone enrichment siblings, so an agent can pick it without opening a schema.

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

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

Gives clear conditional guidance: contacts are omitted unless contact_audience is set, and contact_audience=owners is the path to get owner names, phones with DNC flags, and emails. It stops short of naming sibling alternatives (e.g. enrich_address for a street address, or reverse_geocode), so the agent must infer which enrichment tool fits when it has an address instead of coordinates.

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

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

Annotations only declare readOnly=false/destructive=true/idempotent=false; the description adds the real behavioral context: a paid DealMachine account is required, each returned person costs one people credit, associated properties cost property credits, estimate_cost consumes no credits, and batching reduces requests but not credits. That is meaningful context beyond the annotations, though it never explicitly explains the write/destructive surface implied by destructiveHint=true.

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

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

Front-loaded with the core action and mode split, then returns, then cost/auth constraints. Content is dense but every sentence carries information; the phrase 'or up to 250 names in data sharing location, pagination and options' is slightly garbled but still readable.

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

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

With no output schema, the description compensates by describing return shape (paginated people with phones and emails, optional attached properties) and by covering auth, credit economics, and the estimate-cost preview. For a 10-parameter, nested-object enrichment tool this is close to complete; only error/pagination edge 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%, so baseline is 3, but the description adds cost semantics the schema does not carry: include_properties=true returns associated properties and costs property credits, and estimate_cost=true returns counts without records or credit use. It also frames the data array as a shared-location batch, which is more than a parameter restatement.

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

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

Opens with a specific verb and resource ('Finds people by name') and immediately distinguishes the lookup mode (single last_name with optional first_name/middle_initial) from the batch mode (up to 250 names in data). This clearly separates it from sibling enrichment tools such as enrich_email and enrich_phone.

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 selection guidance between single lookup, batch, adding a location to narrow, and estimate_cost=true as a dry run. It does not name the other people-oriented siblings (people_search, people_count, people_get) as alternatives, so exclusions remain implicit 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 flag destructiveHint=true and openWorldHint=false, so the description's real contribution is the billing model: one people credit per matched person, one property credit per included property, and no charge on a miss. That cost/auth detail is exactly the kind of behavior an agent needs before spending credits. It does not explain why the call is flagged destructive or how multiple matches are resolved.

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 core action first, then the return shape, then billing. Nothing is padding, though the semicolon-chained billing clause is dense and could be split for scanability.

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 job of listing returned fields (name, contact info, demographics, optional properties). Auth and cost are covered, but ambiguity around multiple phone matches and the effect of the location parameter is left unresolved.

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 phone formatting, the fields array, and the location object are already documented. The description only restates the include_properties cost and the required phone, which the schema already carries, and says nothing about how location narrows matches. 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 plus the identifier ('Looks up a person by phone number'), which cleanly separates it from enrich_name, enrich_email, enrich_address and enrich_apn. It also enumerates what comes back, so the agent knows the output shape before calling.

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 context is implied through the paid-account prerequisite and the credit model, which tells the agent this is a metered enrichment call. However, it never names an alternative (e.g., people_search or enrich_name) or states when not to use this tool, so no explicit routing guidance exists.

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, and the description adds cost and limit semantics that annotations cannot express: no data credit charges, uncached reads count toward the API request limit, and identical requests are cached for 15 minutes. It also discloses pagination behavior (omitting search returns all pages), which materially affects invocation.

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

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

Four sentences, front-loaded with what is returned, then filtering behavior, then cost/limit implications, then caching. Every sentence carries information an agent needs; no filler or 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?

With no output schema, the description correctly covers the return shape (field ID, source type, data type, description) and pagination behavior. For a zero-required-parameter read-only listing tool, this is complete enough to invoke confidently without further exploration.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: 'search' is a fuzzy concept match across field metadata rather than an exact filter, and omitting it changes scope from filtered to all pages. It does not elaborate on group_id or source_type semantics, keeping it just short of 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 ('Returns available DealMachine data fields') and enumerates the returned attributes (field ID, source type, data type, description). This is clearly a metadata/schema-discovery tool, distinguishable from sibling search tools like dealmachine_property_search or dealmachine_people_search that consume these fields.

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

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

Gives clear context: use it to obtain field definitions, and 'Reuse these definitions for subsequent lookups' tells the agent to consult this before other calls. It does not explicitly name which siblings consume these fields or when to prefer a different discovery endpoint, so it falls short of full when/when-not 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. The description adds useful operational context beyond annotations: no data-credit charge, uncached reads count toward the API request limit, and identical requests are cached for 15 minutes.

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 compact: four sentences cover purpose, search behavior, cost/rate-limit behavior, and cache reuse. Every sentence supplies useful information without 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 still names the returned filter fields and explains search, billing, rate-limit, and caching behavior. It is sufficient for correct invocation, with the main gap being no explicit routing against sibling metadata 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%, so all parameters are already documented. The description adds meaningful semantics for `search` by naming fuzzy-match targets (labels, aliases, option values) and clarifies the no-search default of returning all pages.

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 DealMachine search filters and enumerates the returned attributes. It is clear, but it does not explicitly distinguish this from sibling metadata tools such as dealmachine_fields.

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 that including `search` performs fuzzy matching while omitting it returns all pages, and recommends reusing definitions because caching applies. It gives no explicit when-to-use or when-not guidance versus sibling tools such as dealmachine_fields.

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 read-only, idempotent, non-destructive behavior. The description adds useful context by saying it returns the original request parameters and paginated entity IDs, and that it does not spend credits, which is not covered by annotations.

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

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

The description is appropriately short and front-loads the key retrieval behavior. The opening 'Get activity' is redundant with the tool name, but the remaining sentences earn their place by describing return contents and cost 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 rich annotations, one parameter, and no output schema, the description is largely complete: it says what record is retrieved and what the response includes. It could be stronger if it mentioned error behavior or pagination mechanics, but no major gap prevents 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?

There is only one required parameter, and the schema includes an example and short description for activity_id. However, the reported schema description coverage is 0%, and the tool description adds no extra guidance on how to obtain or format the activity ID.

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: retrieve the full details of a specific activity record. It implies retrieval by ID, distinguishing it from activity-search siblings, but does not explicitly name or contrast with those alternatives.

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 that this tool is for fetching a known activity record when full details are needed, but it gives no explicit when-to-use guidance, prerequisites, or alternatives such as searching for an activity first.

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 context that is NOT in annotations: results are 'fast' and 'bounded', every hit carries a DealMachine property ID, and the call spends no credits (a real cost concern on a paid-data API with enrich siblings). Return-shape detail is a bonus given 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?

Four tight sentences, front-loaded with the action and scope. Minor waste: 'Retrieves data without changing records' largely restates readOnlyHint/destructiveHint, though the 'or spending credits' 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?

With no output schema, the description correctly compensates by stating what each suggestion contains (property ID, optional normalized city/county). Remaining gaps are minor: how state/lat/lng combine with the text query to affect ranking, and what an empty result looks like.

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 description says nothing about the query/limit/state/latitude/longitude parameters. The reported 0% coverage reflects the undescribed top-level 'query' wrapper, but the nested fields are in fact documented in the schema (min 2 chars, max 10 suggestions, two-letter state, lat/lng used to rank nearby addresses), so the agent is not blind — just unmapped to the description. 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?

Specific verb+resource: 'Autocomplete property addresses. Return fast, bounded street-address suggestions from DealMachine property data.' The word 'autocomplete' plus 'partial street address' clearly separates it from full-query siblings like property_search or location_search, 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?

Usage is implied by 'autocomplete' / 'fast, bounded suggestions' (typeahead-style lookup on a partial string), but the description never states when to use this versus dealmachine_property_search, dealmachine_location_search, dealmachine_post_addresses_validate, or the dealmachine_enrich_* endpoints. The agent must infer the routing.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'retrieves data without changing records' largely repeats structured data. The 'without spending credits' claim is genuinely additive cost context, and the prospect-count note hints at payload shape, but pagination behavior and the mode/driver/date filtering semantics go undisclosed.

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

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

Four short sentences with the core purpose front-loaded. 'List drives. List recorded drives for the workspace.' is mildly redundant, 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?

With no output schema, no annotations covering payload shape, and a nested parameter object at 0% description coverage, the description should explain the mode filter, pagination and date/driver filters. It instead stops at the resource name and a one-line return hint.

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 a nested query object with six undocumented sub-fields (mode enum, page, per_page, started_after, started_before, driver_user_id). The description mentions none of them, so an agent gets no meaning beyond bare property names.

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 recorded drives for the workspace') and notes what each item reports. It does not explicitly distinguish itself from the sibling dealmachine_get_driving_drives_id, but the plural/workspace scope makes the difference inferable.

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 statement of when to use this versus dealmachine_get_driving_drives_id for a single drive, and no guidance on filtering or prerequisites. Only the implicit 'for the workspace' scope hints at usage.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context — 'without changing records or spending credits' — which matters in a toolset where enrichment siblings consume credits, so an agent learns this call is free.

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 substantive sentences that are front-loaded and earn their place. The leading 'Get drive.' fragment merely restates the annotation title and is dead weight.

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

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

With no output schema, the description carries the return-value burden and does so by naming the four payload sections. For a one-parameter read tool that is nearly sufficient; only the relationship to the list endpoint and the ID source are missing.

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

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

The description adds nothing about the single `path.id` parameter, and the reported schema description coverage is 0%. However, the nested schema itself documents the id with examples (`drive_session_501`, `drive_route_7`), so an agent can still call it correctly — a minimum-viable 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 ('Get a recorded drive') and enumerates the returned payload (route, events, visits, prospect links), which goes beyond the title. It does not explicitly distinguish itself from the sibling dealmachine_get_driving_drives list endpoint, leaving the singular-vs-collection distinction to inference.

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: fetching a single drive presupposes an ID, but the description never says to use dealmachine_get_driving_drives first to obtain one, nor does it state any exclusions or preconditions. No explicit when-to-use guidance is present.

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 useful context that it doesn't spend credits, but says nothing about result ordering, page sizes, or response 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?

Three short sentences, front-loaded with the core action and no filler. The opening 'List exports.' slightly duplicates the following sentence, a minor 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?

No output schema and a nested parameter object, yet the description doesn't clarify the query wrapper or what a returned export record contains. It covers the main intent but leaves the calling contract partly 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?

Context reports 0% schema description coverage, so the description should compensate. It mentions pagination and status filtering but doesn't explain the nested 'query' wrapper, the limit range, or offset semantics, leaving real gaps.

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 past exports for your organization'), which clearly distinguishes this from dealmachine_get_exports_exportId (single export fetch). Scope is stated, but no sibling is named explicitly.

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

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

Implies usage for browsing export history, with pagination and status filtering mentioned, but gives no explicit when-to-use vs the sibling get_exports_exportId, nor when-not-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the description's 'without changing records or spending credits' is partly redundant — but it usefully extends that to the credit/billing model, which annotations cannot express. The organization-scoping constraint ('only exports belonging to your organization are accessible') is genuinely new behavioral context an agent needs to predict authorization failures.

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 first two sentences ('Get export by ID. Retrieve a single export by its ID.') are near-verbatim restatements of each other and of the annotation title, consuming space without adding information. The remaining two sentences do earn their place, but the opening 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?

For a simple, annotated, single-parameter read there is nothing critical missing, but the description never says what an export record looks like beyond the field name — status, progress, or a download reference — and no output schema exists to fill that in. An agent calling this cannot anticipate what it will receive.

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 the single parameter is nested inside a 'path' object with an 'exportId' string — a shape the description does not explain at all. 'By its ID' adds nothing the schema does not already say, and gives no hint about ID format or where an agent obtains one (presumably from dealmachine_get_exports).

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 ('Get/Retrieve a single export by its ID'), and the word 'single' implicitly separates it from the sibling list tool dealmachine_get_exports. It never names that sibling, so an agent must infer the distinction from plurality alone.

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

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

Usage is only implied: you need an export ID to call it. There is no explicit statement of when to use this versus dealmachine_get_exports to enumerate exports, nor any note about what to do if the ID is unknown.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so most of the safety profile is structured data. The description adds one genuinely new fact not in annotations – that reads do not spend credits – but says nothing about pagination limits or the default result ordering beyond what the schema shows. With annotations lowering the bar, a 3 fits.

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

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

Three short sentences, but the first ('List all lists.') merely restates the title and is immediately superseded by the second sentence. Folding it into the scoped sentence would make the definition tighter with no loss.

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

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

For a no-required-parameter, read-only collection endpoint with annotations covering side effects and no output schema, this is nearly enough: it states scope, capabilities and credit neutrality. Only the shape/nature of returned list objects is unaddressed, which is a minor gap for a 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?

The description names the four capability axes present in the nested query object (pagination, search, filtering, sorting), which maps loosely onto page/per_page, search, source_type and sort. It adds no defaults, enum values or format detail beyond the schema's own per-field descriptions, so it neither compensates fully nor is useless.

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

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

States a specific verb and resource ('List all saved lists for your organization') and scopes the result set to the caller's org. It distinguishes itself implicitly from the single-list sibling dealmachine_get_lists_list_id by saying 'all lists', but never names an alternative 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: the phrase 'list all lists' suggests it is the collection-level read, contrasting with the *_list_id getter, but no when-to-use/when-not guidance or alternative is named. An agent must infer routing from sibling names.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false. The description's 'without changing records or spending credits' restates the read-only profile but adds a genuinely new fact — no credit consumption — and discloses the returned content. It stays quiet on pagination/error behavior for a nonexistent 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?

Three short sentences, front-loaded with the core action and no filler. Opening 'Get list by ID' mildly duplicates the title, which costs a point 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?

A one-parameter, read-only lookup with no output schema; the description covers what is returned (status, progress, count) and the safety/credit profile, which is enough for an agent to call it correctly. Only the ID-discovery path 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 coverage is 0%, but there is a single nested string parameter (list_id) described as 'List ID'. The description adds only 'by its ID', so it does not compensate for the zero coverage — though the parameter is nearly self-evident. 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 (Get/Retrieve) and resource (list by ID) and enumerates what the payload contains (build status, progress, total count). This distinguishes it clearly from the plural dealmachine_get_lists and from dealmachine_get_lists_list_id_items, though it never names those 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?

Usage is only implied: reaching for this tool when you already have a list_id and want its detail. There is no explicit when-to-use, when-not-to-use, or alternative named (e.g. use get_lists to discover IDs first, use ..._items to fetch members).

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 genuinely new information not in the annotations: that this call spends no DealMachine credits, which is meaningful given the presence of credit-consuming enrich/export endpoints. It stops short of describing pagination behavior or result 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?

At three short sentences it is not bloated, but the first two sentences restate each other ('Get list items' / 'Retrieve paginated items in a list') before the useful credit note. Trimming the redundant restatement would make it tighter.

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 with full annotation coverage and no output schema, the definition is adequate to call the tool. It leaves gaps around where list_id comes from and what an 'item' contains, which matters for an agent deciding how to use the 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 reported as 0% at the top level, but the nested fields (list_id, page, per_page) do carry descriptions in the schema. The description only echoes 'paginated', adding no format, default, or limit detail beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Get list items', 'Retrieve paginated items in a list'), which clearly separates it from list-level tools like dealmachine_get_lists. However, it never names the relevant siblings (dealmachine_get_lists_list_id, dealmachine_list_add_items) so the agent must infer the boundary itself.

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

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

There is no statement of when to use this tool versus alternatives, no prerequisites (e.g., a list_id must come from dealmachine_get_lists), and no exclusions. The only context given is about credits, which is behavioral rather than guidance on tool selection.

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 "without changing records" largely restates structured data. The one genuine addition is "without spending credits" — a cost disclosure an agent cannot get from annotations and that matters for call budgeting. It still says nothing about what happens on an unknown ID or the shape of the returned location.

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?

Short and front-loaded, but "Get location." followed immediately by "Retrieve a specific location by its ID." is a redundant restatement that could be collapsed. The remaining sentences are efficient and earn their 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 single-parameter, read-only, idempotent lookup with no output schema, this covers what an agent needs: what it fetches, that it is identified by ID, and that it costs nothing and mutates nothing. Depth beyond this is optional for such a simple 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 registers as 0% at the top level, but the nested locationId property does carry both a description and an example (loc_county_48201 / loc_city_7333). The prose adds only "by its ID" — no format rules, prefix semantics, or whether city/county/state IDs are all valid. Baseline 3 is appropriate since the schema itself handles most of 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 ("Retrieve a specific location by its ID"), which is unambiguous about what comes back. It does not name the obvious sibling dealmachine_location_search, so an agent must infer that the search tool is the way to discover an ID rather than inventing one.

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

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

No when-to-use / when-not-to-use guidance and no named alternative. The phrase "by its ID" weakly implies a lookup-once-you-have-an-ID pattern (with dealmachine_location_search as the discovery path), but that inference is left entirely to the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description's 'without changing records or spending credits' partly restates that but adds genuinely new context — that mail operations consume credits and this call does not — and it discloses the shape of the response (totals plus paginated campaign list), which matters since 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?

Three sentences, front-loaded with the core purpose and zero wasted prose. The opening 'Get mail analytics summary.' is a near-verbatim restatement of the title and could be dropped, but the remainder is dense and useful.

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 payload (account-wide totals: sent, delivered, failed, opens, unique openers, average open rate, plus paginated per-campaign engagement). Annotations cover the safety profile and the nested schema covers inputs, so an agent has enough to invoke it correctly; only the date-filter semantics go unmentioned in prose.

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 description says nothing about page, per_page, start_date, end_date, or launched_only. In practice the nested schema carries a description for each of the five properties (including that dates filter by campaign launch date and are inclusive), so the parameter semantics are not lost — but the description contributes no additional meaning beyond the nested object, which is especially relevant given the reported 0% top-level coverage.

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

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

The description gives a specific verb and resource ('Get account-wide mail analytics') and enumerates what is returned: aggregate totals plus a paginated list of campaigns with per-campaign engagement. The 'account-wide' qualifier implicitly separates it from per-campaign siblings like dealmachine_get_mail_campaigns_id_analytics, but no sibling is named explicitly.

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

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

There is no explicit statement of when to choose this over dealmachine_get_mail_analytics_timeseries, dealmachine_get_mail_campaigns, or the per-campaign analytics tools. The only steer is the phrase 'account-wide', which implies scope but leaves the agent to infer the routing decision.

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. The description adds useful behavioral context beyond annotations: missing buckets are zero-filled, scans include secondary_value, and the call does not spend credits.

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 and compact: the core purpose comes first, followed by metric semantics and two important behavioral details. Each 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 enough about the returned series: it is continuous due to zero-filled buckets, and scans include secondary_value. It does not describe response envelope or date-label format, but is otherwise complete 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?

The description adds meaning beyond the schema by defining scans as QR/link views and explaining secondary_value for that metric. It restates the metric and day/week bucket choices, but does not add guidance for the date-range parameters.

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

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

States a specific verb and resource: get an account-wide mail analytics time series for a single metric, bucketed by day or week. The purpose is clear, but it does not explicitly contrast with sibling tools such as the mail analytics summary or campaign analytics.

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: use this when you need a metric charted over time. However, it gives no explicit when-to-use versus summary or campaign-analytics alternatives, and no exclusions or prerequisites.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely non-obvious behavior beyond them: archived campaigns are hidden by default, and the call spends no mail credits — a domain-specific cost signal that matters in this tool family.

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

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

Front-loaded with the core action, then behavior, then the credit note. Slightly redundant opening ("List campaigns" followed immediately by "List mail campaigns..."), but every later sentence carries real 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 filtered list tool with no output schema and all-optional nested params, the description covers statuses, default exclusions and the cost profile. Missing are result ordering/pagination expectations and what a campaign object contains, though the absence of an output schema lowers that burden.

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 nested schema already documents page, search, per_page, status and accepting_properties in detail, so the description mostly restates them. It does add value by explaining the default archived exclusion and the accepting_properties predicate, but it omits search/pagination semantics and never mentions the legacy completed/cancelled enum values present 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?

States a specific verb and resource ("List mail campaigns for your organization") plus the scope of filtering, which cleanly separates it from dealmachine_get_mail_campaigns_id (single campaign) and the mail analytics/design/return-address list tools. An agent can identify the right tool without opening a schema.

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

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

Gives concrete usage conditions: use accepting_properties=true to find campaigns that can take properties now, and supply status=archived to see archived campaigns. It does not explicitly name the sibling to use for a single campaign or for analytics, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description adds the domain-specific note that it does not spend credits, which matters for a mail-campaign tool with wallet semantics. 'With steps' also hints at the returned payload, though it could say more about what the steps contain.

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 verb and resource. 'Get campaign' plus 'Get a single campaign by ID' is slightly redundant but each clause adds scope ('single', 'with steps', 'no credits').

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 explaining the return value; 'with steps' hints at structure but doesn't describe fields, error behavior on unknown IDs, or whether steps include design/recipient detail. Adequate for a simple single-resource GET but not complete.

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

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

Schema description coverage is 0% for the single nested 'path.id' parameter, but the description's 'by ID' adequately conveys that the input is a campaign identifier. It adds no detail about the nesting structure or ID format, so it only marginally compensates 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?

States a specific verb and resource ('Get a single campaign by ID with steps'), distinguishing it from the list sibling dealmachine_get_mail_campaigns by emphasizing 'single' and the inclusion of steps. It doesn't differentiate itself from the analytics/recipients/cost-estimate sub-resource siblings, but the core 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?

'Retrieves data without changing records or spending credits' implies a safe read context, but there is no explicit guidance on when to use this endpoint versus dealmachine_get_mail_campaigns_id_analytics, _recipients, or the list endpoint. 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is mostly covered. The description adds a genuinely non-derivable fact: it does not 'spend credits', which matters in a mail tool where campaigns consume wallet balance. It stops short of describing result shape, pagination, or any date-range behavior of the returned analytics.

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, but the opening 'Campaign analytics.' is pure duplication of the annotation title and earns nothing. The substantive content is front-loaded only after that waste, and the most differentiating fact (no credit spend) sits at the end.

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 saying what comes back, and 'delivery and engagement analytics' gives a usable if coarse sense of the payload. It does not specify metric names, granularity, or time window, which leaves real gaps for a tool whose entire value is the returned dataset.

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 (path.id) with 0% schema description coverage; the schema only offers the generic label 'Resource ID'. The description's mention of 'a campaign' is the only hint that the id is a campaign identifier, but it gives no format, no source (e.g. from dealmachine_get_mail_campaigns), and no indication of the nested path wrapper.

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: 'Get delivery and engagement analytics for a campaign.' That is clear and the per-campaign scope narrows it against the account-level siblings, but it never names those siblings (dealmachine_get_mail_analytics_summary, dealmachine_get_mail_analytics_timeseries), so the agent must infer the boundary. The leading fragment 'Campaign analytics.' merely repeats the annotation title.

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 phrase 'for a campaign' – an agent can deduce this is the per-campaign view rather than the aggregate summary/timeseries. There is no explicit when-to-use statement, no exclusion against the four other campaign-scoped siblings (cost_estimate, properties_estimate, recipients), and no stated preconditions.

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, and the phrase 'without changing records or spending credits' largely restates those. The one genuinely additive detail is that the estimate includes a wallet balance check, which is useful behavioral context.

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

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

Front-loaded with the core action ('Estimate campaign cost') followed by scope and safety details in three tight sentences. Little waste, though the trailing safety sentence is largely redundant with 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?

No output schema exists, so the description should say more about what the estimate returns (cost breakdown fields, wallet balance structure). It conveys purpose and safety but leaves return content underspecified for a tool whose value is the estimate payload.

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

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

There is a single nested path.id parameter with generic 'Resource ID' schema text (0% meaningful coverage). The description's reference to 'campaign' implies id is a campaign id, adding modest meaning, but it doesn't clarify path nesting or what id must reference.

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 (estimate) and resource (campaign cost) with added scope that it includes a wallet balance check. However, it does not distinguish itself from the very similar sibling dealmachine_get_mail_campaigns_id_properties_estimate, leaving ambiguity about which estimate to use.

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?

'for launching a campaign' implies pre-launch usage, but there is no explicit when-to-use, when-not, or alternative routing despite several competing estimate/wallet siblings. Usage is only inferable from context.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: no charge or mutation occurs, charge due today vs later charges, wallet/auto-reload coverage, upper-bound billing semantics, and the paused-campaign case where charge due today is 0 and charged_on_resume is true. That is exactly the behavioral detail an agent needs before quoting a price.

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 purpose and cost breakdown, followed by the upper-bound and paused-campaign rules. The closing sentence 'Retrieves data without changing records or spending credits' restates what the second sentence already said and what readOnlyHint/destructiveHint annotations cover, so there is minor 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?

Covers the full decision surface for a read-only estimate: what is returned conceptually (charge today, later charges, wallet coverage flag), no side effects, billing edge cases (skipped properties, paused campaigns). With no output schema needed for an estimate preview and annotations carrying the safety profile, 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?

With schema description coverage reported at 0%, the description must carry the load. It clarifies what count means (properties planned to add, upper bound, skipped ones not charged), which is valuable, but it never explains the path.id parameter beyond the schema's generic 'Resource ID' (i.e., that it is the campaign id). Partial compensation only.

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: estimating the cost of adding a number of properties to a mail campaign. The line 'Nothing is added or charged' implicitly distinguishes it from dealmachine_mail_campaign_add_properties, and the count framing separates it from the campaign cost_estimate sibling. An agent can tell what this 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?

Clear usage context: run this to preview the charge before adding properties, with the caveat that the count is an upper bound because skipped properties aren't charged. It explains paused-campaign behavior as a usage scenario. It stops short of explicitly naming dealmachine_mail_campaign_add_properties as the follow-up action, so no named alternative.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so "retrieves data without changing records" largely repeats structured data. The one genuine addition is "without spending credits" — a cost trait annotations cannot express — but pagination behavior and result size are never 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?

Short and front-loaded, but the second sentence restates the first ("List campaign recipients" / "List recipients enrolled in a campaign"), wasting budget that could have documented the id or pagination.

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 should carry the return shape — it only mentions a delivery status field. With 0% schema coverage and two undocumented parameters including nested pagination, the definition leaves too much for an agent to infer before a correct call.

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 description adds nothing: the nested `path.id` is only labeled "Resource ID" and the description never says it is the campaign id. The `page`/`per_page` query parameters are completely undocumented in both schema and description, so an agent must guess the pagination contract.

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?

"List recipients enrolled in a campaign with their delivery status" gives a specific verb, resource, parent scope, and payload. It clearly differs from dealmachine_get_mail_campaigns_id (campaign itself) and dealmachine_get_mail_campaigns_id_analytics, though it never names a sibling explicitly.

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

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

Usage is implied: read-only listing of recipients under one campaign. It never states when to prefer this over the campaign analytics, cost estimate, or properties estimate siblings, nor any prerequisite like campaign existence or required plan tier.

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. The description adds that retrieval does not spend credits, which is useful context beyond the annotations, but it does not disclose pagination behavior, filtering behavior, or what the returned design listings contain.

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 short and front-loaded, but the first two sentences are largely redundant: 'List designs' repeats the annotation title, and 'List mail designs for your organization' extends it. The final sentence adds behavioral context.

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 endpoint, the description covers the core operation and notes that no credits are spent. However, it omits any context about the available filters and pagination, which are relevant to invoking this tool correctly despite being present in the nested schema.

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

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

The description does not mention the query object or any of its filters such as page, size, search, status, or per_page. Context signals report 0% top-level schema description coverage, and although the nested schema has some field descriptions, the description itself fails to compensate by explaining how to use the filtering and pagination parameters.

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

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

The description states a specific verb and resource: 'List mail designs for your organization.' It is clear what the tool does, though it does not explicitly differentiate this list tool from the sibling single-design tool dealmachine_get_mail_designs_id or creation/patch/delete design 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 listing intent is implied by 'List mail designs for your organization,' but there is no explicit guidance on when to use this tool versus fetching a single design by ID, creating a design, or modifying one. No alternatives or exclusions 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description nonetheless adds two pieces of non-annotation context: the response includes HTML content, and the call does not spend mail credits — the credit behavior is domain-specific and not derivable from the annotations.

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

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

Three short sentences, no padding, with the core action and the HTML-content scope front-loaded. The opening 'Get design.' is redundant with the following sentence but costs 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?

There is no output schema, so the description carries the burden of telling the agent what comes back; it does name HTML content, which is the most important field, but not the other design attributes. Nothing is said about behavior when the ID is invalid or 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 0% and there is a single nested 'path' object containing an 'id' string. The description conveys that the tool takes a design ID, which is the essential meaning, but says nothing about the nested path wrapper or formats/validation of the ID.

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

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

States a specific verb and resource ('Get a single design by ID') and adds scope ('including HTML content'). It implicitly distinguishes itself from the sibling listing tool dealmachine_get_mail_designs by saying 'single design by ID', but never names the list tool 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: an agent can infer you call this when you already hold a design ID and want the full record, versus listing designs. There is no explicit when-to-use, when-not-to-use, or named alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real value beyond them by stating that calls spend no credits and that the default address is returned first — the credit cost point in particular is not derivable from annotations.

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

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

Front-loaded and short, with the ordering and cost facts placed after the core statement. The first two sentences are largely redundant ('List return addresses' then 'List all return addresses for your organization'), so a small amount of space 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 zero-parameter read-only list call with full annotation coverage and no output schema, the description covers what the tool returns at a conceptual level and costs nothing to run. It stops short of describing what fields a return address record contains, which is a modest gap given there is no output schema.

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

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

The tool takes no parameters, so the baseline is 4; there is nothing the description could clarify about inputs. It appropriately does not invent parameter talk, and the only structural note ('default address is listed first') concerns output ordering rather than inputs.

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

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

States a specific verb (list) and resource (return addresses) and scopes it to the whole organization via 'all return addresses for your organization'. The word 'all' implicitly distinguishes it from the sibling dealmachine_get_mail_return_addresses_id, but it never names that sibling explicitly, so differentiation is inferential rather than stated.

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

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

The collection-wide framing implies this is the enumerate-everything call versus the by-id lookup, but there is no explicit when-to-use or when-not guidance. With zero parameters, there is also no hint about filtering or paging, leaving the agent to infer that the full set comes back in one call.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds one piece of genuine context beyond them — 'without spending credits' — which matters in a credit-metered product, but the 'without changing records' clause merely restates readOnlyHint.

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 first two sentences are near-duplicates ('Get return address.' / 'Get a single return address by ID.'), so one of three sentences is largely wasted. The credit statement is front-loaded reasonably but the opening is redundant rather than efficiently 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?

This is a simple single-resource read with a one-parameter nested schema, full annotation coverage, and no output schema, so the description does not need to explain return values. What remains missing is only minor: how to obtain the ID and what happens when it is 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?

Schema description coverage is 0% and the single nested parameter (path.id) is only labeled 'Resource ID'. The description says lookup is 'by ID' but adds no format, source, or validity guidance, so it does little to compensate for the thin schema.

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

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

The description names a specific verb and resource ('Get a single return address by ID') and the word 'single' implicitly separates it from the sibling list tool dealmachine_get_mail_return_addresses. It stops short of naming the sibling explicitly, so it is clear but not fully differentiated.

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

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

'Get a single return address by ID' implies this is the fetch-one counterpart to the list endpoint, but there is no explicit statement of when to use this versus the list or patch/delete siblings. Usage must be inferred from the name and phrasing.

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 structurally; the description still adds the non-obvious fact that this call spends no credits, which matters in a mail product where sending does cost credits. It does not discuss permissions or whether organization vs. sub-account scoping applies.

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

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

Three compact sentences, front-loaded with the verb and resource, then the field detail and the cost/reversibility note. The opening 'Get mail settings.' largely restates the tool name and is the only wasted line.

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 carries the return-value burden and does so by enumerating the key settings returned. An agent has enough to decide to call it and to know what to expect, though it lacks any sense of nested structure or fallback behavior when defaults are unset.

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 there is no parameter semantics to explain — baseline 4 applies. The field list in the description functions as informal return-value information rather than duplicating schema content.

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 (get) and resource (organization-level mail settings) and immediately scopes it as the defaults applied to new campaigns, which separates it from campaign-, design-, and return-address-level siblings like dealmachine_get_mail_campaigns_id or dealmachine_get_mail_return_addresses. The enumerated fields (postcard size, sender name, frequency limit, QR code URL, signature image) make the resource concrete.

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?

Phrasing like 'act as defaults for new campaigns' tells an agent the context in which this data is relevant, and 'retrieves data without changing records' implies the read-only path. It does not explicitly name the write counterpart dealmachine_patch_mail_settings or state when not to use this call.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the description's 'retrieves data without changing records' largely restates structured data. It does add one genuinely useful behavioral fact — no credits are spent — plus the shape of the returned data, but says nothing about response format, freshness, or error cases.

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 action, with no wasted clauses. The opening 'Get wallet balance.' is near-redundant with the sentence that follows it, a minor trim opportunity.

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, no output schema, and full annotation coverage of the safety profile, the description carries exactly the load it needs to: what is fetched, that it is free, and that it is non-mutating. Nothing an agent needs in order to call 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 for the description to disambiguate. The mention of pending charges and auto-reload settings clarifies what the parameterless call yields, which is a small value-add.

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

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

States a specific verb and resource ('Get wallet balance') and enriches it with the payload contents ('pending charges and auto-reload settings'), which tells the agent what data comes back. It does not explicitly distinguish itself from the related wallet siblings (get_mail_wallet_pricing, get_mail_wallet_transactions), 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?

Usage is only implied by the resource itself — an agent can infer this is the balance-check tool. There is no explicit when-to-use, no exclusion telling the agent to prefer get_mail_wallet_transactions for history or get_mail_wallet_pricing for rates, and no prerequisites mentioned.

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 the safety bar is lower. The description still adds real context beyond them: prices are in cents per postcard and the call does not spend credits — a meaningful clarification for a wallet-adjacent endpoint.

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

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

Four short sentences, front-loaded with the core action, with no filler. Minor redundancy: 'Get mail pricing' and 'Get postcard pricing' restate the same operation, and the no-write clause partly duplicates the readOnlyHint annotation.

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 full annotation coverage and no output schema, the description covers what the call does, its units, and its side-effect profile. It could say more about the shape of the response (e.g., whether volume tiers are returned), which is the only remaining gap.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies pricing is derived from the caller's plan rather than any input argument, leaving nothing for an agent to supply or misconfigure.

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

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

States a specific verb and resource: 'Get postcard pricing for your plan,' with the unit ('cents per postcard') made explicit. It is distinguishable from sibling cost/balance tools like dealmachine_get_mail_campaigns_id_cost_estimate and dealmachine_get_mail_wallet_balance, though it never names those alternatives.

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

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

Usage is only implied: an agent can infer this is the tool for looking up per-postcard prices before sending a campaign. There is no explicit guidance on when to prefer this over the cost estimate or wallet balance siblings, and no stated prerequisites (e.g., plan required).

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds a useful clarification that it does not spend credits (meaningful in a wallet context), but otherwise largely restates the annotation profile without covering pagination or response 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?

The first two sentences are redundant ("List wallet transactions" and "List wallet transaction history"), diluting the front-loaded clarity. Short overall, but a sentence could be merged 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?

Annotations cover the safety profile and the nested schema documents all filters, so little is missing for a read-only list tool. Return format and pagination behavior are undocumented, but no output schema exists to carry that, so a small gap remains.

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 schema's nested query fields (page, type, per_page, campaign_id, reference_type) each carry descriptions, even though top-level coverage reports 0%. The description adds nothing beyond 'optional filtering', so the schema does the heavy lifting — 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: "List wallet transactions" plus "transaction history with optional filtering." Clear for an agent, though it does not distinguish itself from siblings like dealmachine_get_mail_wallet_balance or dealmachine_get_mail_wallet_pricing.

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

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

"with optional filtering" implies the tool's scope but gives no guidance on when to use it versus viewing balance/pricing, and no exclusions or prerequisites. 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 cover readOnly/idempotent/non-destructive, so the description earns credit for what they don't say: "without ... spending credits" is meaningful domain context for a paid-credit API, and "if there is one" discloses that a missing prospect is a normal outcome rather than an error.

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 the core action front-loaded and the credit/read-only reassurance last. Slight redundancy between sentence one and two ("Get prospect by record" vs "Look up the prospect that tracks..."), but 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 and a nested query object, the description should say more about the return value: does a hit return a full prospect object, and what is returned when no prospect exists? It only gestures at this with "if there is one."

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

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

The description itself gives no parameter detail, and the reported coverage is low, but the nested schema fully documents record_id formats (prop_123, person_456, bare number) and the record_type enum. The description partially compensates by enumerating 'property, person, or company', which mirrors the enum 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 specific verb and resource ("Get prospect by record") and clarifies the lookup key: the prospect that tracks a property, person, or company. That distinguishes it from ID-based siblings such as dealmachine_prospect_get, 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: the phrase "if there is one" signals a nullable lookup and hints you should call it when you already have a property/person/company record. There is no explicit guidance on when to prefer this over dealmachine_prospect_get, dealmachine_prospect_search, or dealmachine_post_prospects_check.

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, but the description adds 'without spending credits', which is real domain context not present in the structured fields and matters for a paid-credit API. It stops short of describing the returned grouping shape or any rate/latency 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 with the verb-first headline front-loaded, followed by breakdown dimensions, scope, and cost behavior. No wasted clause, though the opening 'Count prospects.' largely restates 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?

No output schema exists, so the description wisely names the aggregation dimensions (lifecycle, record type) as a proxy for the return shape, and it covers both scope modes plus the no-credit guarantee. The only shortfall is the absence of any explanation of the nested query wrapper for the single optional 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 0% for a nested query object containing list_id, so the description must carry the burden, and it partially does by clarifying that the single list_id selects list-scoped counting versus workspace-wide counting when omitted. It adds no format guidance (the schema requires a UUID) and does not explain why list_id sits inside a nested 'query' object.

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 ('Count') plus the resource ('prospects') and narrows the result to two useful breakdowns, lifecycle and record type. An agent can tell this apart from dealmachine_prospect_search or dealmachine_get_prospects_by_record. It does not explicitly distinguish itself from the similarly named dealmachine_people_count and dealmachine_property_count siblings, which is the only gap.

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 scope is implied ('for the workspace or one list'), which tells the agent the two modes of use, but there is no explicit when-to-use guidance, no exclusion of alternatives like prospect_search or people_count, and no statement that list_id omission means workspace-wide.

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 bar is lower. The description adds useful context that results are newest first and that the call does not spend credits, but it does not mention pagination behavior, auth requirements, or response size.

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

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

The description is front-loaded with the core action and then gives scope, ordering, and read-only/no-credit behavior in a compact set of sentences. There is no filler or repetition that wastes the agent's attention.

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?

It gives enough context to understand what is listed and how it is ordered, and annotations cover the safety profile. However, for a filtered list endpoint with no output schema, it omits response shape, pagination expectations, and any guidance on the available filters.

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 description never mentions the required prospect ID or the since, category, page, or per_page filters, so it adds no parameter-level meaning. With schema description coverage reported at 0%, the description does not compensate for that 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: 'List prospect activity' for a prospect's record in this workspace. It also scopes the result set to everything that happened to that prospect, newest first, and enumerates the event categories, which distinguishes it from single-activity and search-oriented siblings.

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

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

The description does not say when to use this tool versus alternatives such as the activity search or single-activity endpoints. It implies the use case by saying it lists prospect activity, but provides no explicit when-to-use or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'retrieves data without changing records' is largely redundant. The one genuinely additive fact is 'without ... spending credits', but the description still says nothing about what the listing contains or whether it is paginated.

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

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

Two short sentences with the operation front-loaded; nothing is buried. The second sentence spends most of its words repeating the read-only annotation, which dilutes it slightly.

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

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

No output schema exists, so the description is the only place to learn what a file listing looks like (ids, names, sizes, pagination). It provides none of that, though the single-parameter surface keeps the tool usable without it.

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

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

Schema description coverage is reported at 0% and the description never mentions path.id. However there is only one required parameter nested under a wrapper, and the inner schema supplies both a description ('Prospect ID') and an example ('prospect_123'), so the gap is small rather than critical.

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?

'List prospect files' gives a specific verb plus resource and the name scopes it to a single prospect. It is distinguishable from siblings like dealmachine_get_prospects_id_photos and dealmachine_get_prospects_id_notes by resource type, though it never says so 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 statement of when to use this versus the closely related dealmachine_get_prospects_id_files_file_id_download, nor any prerequisite or pagination context. The agent must infer the split between listing metadata and downloading content.

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/destructive/idempotent status, so the safety profile is covered. The description adds non-obvious behavior beyond the annotations: a 5-minute signed URL and the redirect-vs-JSON response mode, which are exactly the operational details an agent needs. Error behavior (missing file, expired URL handling) is not covered, keeping it below 5.

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

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

Front-loaded with the core action and tight at four short sentences. The final sentence about not changing records or spending credits largely repeats the readOnly annotations, which is mildly redundant but still useful reassurance.

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 download tool with no output schema, the description covers the key calling modes (redirect vs JSON) and URL expiry. Missing only edge behavior such as not-found or expired-URL handling.

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% at the parameter level, though nested `id` and `file_id` have examples and descriptions. The description only clarifies the `redirect` query parameter by showing `?redirect=false` yields JSON; it does not state the default behavior explicitly or explain the `path`/`id`/`file_id` structure, so compensation is partial.

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

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

States a specific verb and resource — “Download prospect file” — which cleanly distinguishes it from sibling `get_prospects_id_files` (listing files) and `delete_prospects_id_files_file_id`. 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?

The download context is clear and the `redirect=false` guidance tells the agent how to request a JSON URL rather than a redirect. It does not explicitly mention when to use this instead of the file-listing tool, but the purpose 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 cover readOnly, idempotent and non-destructive, and the description adds two things they don't: the newest-first ordering and that the call spends no credits. It still omits pagination behavior and result shape, but the credit and sort context is genuinely additive.

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

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

Three short clauses, front-loaded with the verb and resource; no filler. The second clause ("Notes on the prospect") is mildly redundant with the first sentence but not wasteful.

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

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

For a read-only paginated list with no output schema, the definition leaves the caller without guidance on paging defaults, result contents, or empty-state behavior. Safety profile is handled by annotations, but the paging story is missing from both description and (reported) schema coverage.

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 description mentions no parameters at all, and with schema description coverage reported at 0% for this definition, nothing in the description compensates for the nested path.id and query.page/per_page inputs. An agent must read the raw schema to learn required fields and the 100-item cap.

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

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

States a specific verb and resource ("List prospect notes") and adds scope detail ("Notes on the prospect, newest first"), which separates it from the sibling that fetches a single note by id. It does not explicitly name that sibling, so differentiation is implied rather than stated.

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

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

Usage is only implied: "Retrieves data without changing records or spending credits" signals a read-only retrieval path, but there is no statement of when to choose this over dealmachine_get_prospects_id_notes_note_id or how it relates to activity/files/tags endpoints on the same prospect.

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 'retrieves data without changing records' largely restates them. The one genuine addition is that the call spends no credits, which is not covered by annotations, but nothing is said about what a note contains or error/not-found 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?

Two short sentences, front-loaded with the purpose. There is a stray double space and the second sentence is filler given annotations, but overall there is no bloat.

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 fetch of one note, the annotations plus schema examples are nearly sufficient, and no output schema exists to explain return shape. Still, an agent gets no information about the returned note's fields or ID format requirements, leaving a gap for a nested-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?

Reported schema description coverage is 0% at the top level: the single 'path' object carries no description, and the description adds no information about the prospect ID or note ID beyond the schema examples. The description does nothing to compensate for the undocumented container parameter.

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

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

States a specific verb and resource ('Get prospect note'), which cleanly distinguishes it from the listing sibling dealmachine_get_prospects_id_notes and the mutating dealmachine_patch/delete_prospects_id_notes_note_id tools. It is clear, though it doesn't explicitly name those 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?

No guidance on when to use this rather than the notes-list tool or the patch/delete variants. The only usage-adjacent statement is about credits, not about tool selection.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces that while adding genuinely new facts: results are ordered 'newest first', the call spends no credits, and it is restricted to property prospects. It does not cover paging, result volume, or what happens for non-property prospects.

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

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

Four short sentences, all front-loaded with the resource and ordering stated first. No filler, though the clipped sentence fragments read slightly telegraphic rather than fully polished.

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

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

For a single-parameter read-only list call with rich annotations and no output schema, the description covers scope, ordering, and cost profile. Only the return shape (photo URLs?) and paging behavior remain unstated, which is a minor gap at this complexity.

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

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

Only one parameter (nested path.id), and the schema already carries an example ('prospect_123') and a description despite the reported 0% aggregate coverage. The description implies the parameter via 'of the prospect's property' but never states the required prospect ID or whether it accepts IDs from any source, so it adds 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?

Specific verb plus resource ('List prospect photos') with added scope: 'Photos of the prospect's property, newest first' and 'Property prospects only'. An agent can distinguish this from dealmachine_post_prospects_id_photos and dealmachine_delete_prospects_id_photos_photo_id on verb alone.

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

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

'Property prospects only' is a genuine precondition that tells the agent when this call is valid. However, it never contrasts with the closely-named sibling dealmachine_get_prospects_id_files (files vs photos), so the choice between the two is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description nonetheless adds something the annotations cannot express – 'without changing records or spending credits' – which tells the agent this call is free and side-effect-free, a useful trait for a credit-metered API.

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 the verb and scope up front. The opening 'List prospect tags' is largely restated by the following sentence, a minor redundancy, but nothing is padded or 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 carries the return-shape burden, and it does: the agent learns it gets the tag catalog plus an `assigned` flag. Missing only minor operational context such as ordering or whether unassigned tags are included by default.

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

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

There is a single nested parameter (`path.id`), and the description adds nothing about it – no note on id format beyond the schema's own example, and no explanation of behavior for an unknown prospect. With one param and effectively low schema documentation coverage at the nested level, this is baseline-adequate but not compensatory.

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

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

The description names a specific verb and resource ('List prospect tags') and clarifies the return shape: the tag catalog annotated with an `assigned` flag for this prospect. That scope detail distinguishes it from the global `dealmachine_tags_list`, though it never names the sibling explicitly.

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

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

Usage is only implied – an agent can infer it should call this to see which tags are attached to a prospect, but the description states no when-to-use condition, no prerequisites (e.g. needing a valid prospect id), and never points to alternatives like `dealmachine_prospect_tags_set` or `dealmachine_tags_list`.

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 safety basics are covered. The description adds genuinely useful context for this API: it explicitly says the call does not spend credits, which matters in a toolset where enrichment calls do consume credits.

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 purpose and followed by the returned fields. The opening 'Get subscription status.' largely restates the title/annotation, so one small redundancy, but nothing else 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?

With no input parameters, no output schema, and full annotation coverage, the description carries its part: it names the returned fields (plan, billing cycle, credit caps) so the agent knows what it gets back. Only the relationship to sibling account/usage tools 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?

The tool takes zero parameters, so the baseline is 4. The description correctly says nothing about inputs and avoids inventing parameter details that do not exist.

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 ('Get subscription status') and enumerates the returned content — plan details, billing cycle, credit caps — which separates it from siblings like dealmachine_usage (consumption stats) and dealmachine_get_mail_wallet_balance (mail credits only). It never names those siblings, so differentiation is implicit rather than explicit.

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

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

Usage is only implied by 'your current' — an agent can infer this is the account-level subscription lookup, but there is no explicit when-to-use guidance and no stated boundary against dealmachine_account or dealmachine_usage.

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 fully covered. The description adds one genuinely useful fact beyond them: the call does not spend credits. Beyond that it adds no behavior detail, such as what happens on an unknown tag 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 short sentences, front-loaded with the operation. The second sentence is mildly redundant with readOnlyHint but still carries the credit-cost fact, so the length is justified.

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?

Adequate for a simple single-record read whose safety profile is fully declared by annotations and whose sole parameter is described in schema. It omits the return shape and not-found behavior, which would matter because there is no output schema.

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

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

Only one parameter, and the nested id field already carries a description and example ("Tag ID, e.g. tag_31") in the schema. The prose adds nothing about the id, so it neither compensates nor detracts from the schema.

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

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

"Get tag" states a specific verb and resource, but it largely restates the tool name and annotation title. It does not differentiate this single-tag fetch from the sibling dealmachine_tags_list, which retrieves tags in bulk.

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 never says when to use this tool versus dealmachine_tags_list, dealmachine_patch_tags_id, or the delete variant. The only guidance is an implicit read-only framing ("without changing records"), which is not an alternative-selection 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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is fully covered structurally. The description's "retrieves data without changing records or spending credits" mostly restates that, though the no-credit-cost detail is genuinely additive for an agent weighing call budget. It says nothing about pagination, ordering, or result 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?

Short and front-loaded, with the core scope stated in the first two sentences. "List tasks." followed by "List all tasks for the organization." is slightly redundant but costs 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 zero-required-parameter list tool with full annotation coverage and a documented nested schema, the description covers purpose, scope, filters and cost profile. With no output schema, a note on task fields or default result ordering would close the remaining gap, but nothing needed to call 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?

Top-level schema coverage is 0% (all params nested under query), so the description has to compensate and does partially by naming the status, search and assignee filters. It omits page and per_page entirely, leaving pagination semantics to the nested schema 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 ("List tasks") and adds the scope constraint ("all tasks for the organization"), which separates it from the single-record sibling dealmachine_get_tasks_id. It never names a sibling explicitly, so the distinction is inferred rather than stated.

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

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

"Optionally filter by status, search, or assignee" implies when the filter parameters are useful, but there is no explicit guidance on when to prefer this over dealmachine_get_tasks_id or how pagination should be driven. Usage is implied rather than directed.

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 'without changing records' largely restates structured data. The one genuinely additive claim is 'without spending credits', which is domain-specific cost context the annotations do not carry, but return shape and error behavior (e.g. unknown ID) are left unstated.

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 first two sentences are redundant ('Get task. Get a single task by ID.'), restating the title before the substantive sentence. The credit/cost note is useful but the opening wastes 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?

For a single-parameter read tool with safety annotations covering the side-effect profile, the definition is minimally sufficient. However, with no output schema and no description of the returned task object, an agent gets no picture of what a successful call yields.

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 nested path.id parameter with effectively no schema documentation beyond the label 'Task ID' (coverage reported as 0%). The description says 'by ID' but adds nothing about the identifier's format, source, or validation, so 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 verb and resource ('Get a single task by ID'), which clearly distinguishes it from the list variant dealmachine_get_tasks and the mutating siblings patch/delete_tasks_id. It stops short of naming those siblings, so the differentiation comes from the name and phrasing rather than explicit routing.

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

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

'By ID' implies the caller must already hold a task identifier, but the description never says where to obtain one (e.g. from dealmachine_get_tasks) or when to prefer the single-item fetch over the list endpoint. 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the response includes a description and full example request body per event, and the call spends no credits — a DealMachine-specific cost detail not present in annotations.

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