FirmLedger

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds real context beyond them: this is a Pro-tier tool and only *approved* records count toward a positive match, which materially affects interpretation of results.

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

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

One front-loaded sentence carries the action, the result, and the rationale. The trailing 'is this site legit?' clause is slightly decorative but earns a little of its place by naming the intent.

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

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

No output schema exists, so the description must carry return-value burden; it says only that it returns 'that record' without describing the shape or the miss case (what a negative result looks like). Adequate but incomplete for a lookup tool.

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

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

Schema coverage is 100% with a single well-described param ('A domain such as "example.co.ke" or a full URL'). The description's 'domain or URL' phrasing matches the schema but adds no format or normalization detail beyond it, so baseline 3 applies.

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

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

States a precise verb+resource: given a domain/URL, report whether an approved FirmLedger record uses it and return that record. This is clearly distinguishable from sibling read tools like get_listing or search_listings, though it 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?

The description supplies a usage context ('is this site legit?' questions), which implies when to reach for it, but gives no when-not guidance, prerequisites, or named alternatives among the 35 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds beyond that the 'approved' restriction on eligible companies and the 2-4 cardinality, which is genuinely useful selection 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 purpose, then usage. The attribute enumeration is long but earns its place by defining the comparison output, and there is no filler.

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

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

No output schema exists, so the description usefully enumerates the rows returned (entity type, category, location, founded, etc.), making the return shape reasonably predictable. Minor gap: no note on error handling for fewer than 2 or more than 4 entries.

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

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

Schema description coverage is 100% and the single 'listings' parameter already documents accepted identifier formats (slug, name, FL-ID, URL). The description only restates the 2-4 bound, so it adds little beyond the schema; baseline 3 applies.

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

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

States a precise verb and resource ('Compare 2 to 4 approved FirmLedger companies side by side') and enumerates the compared attributes, so an agent can tell it apart from search_listings or get_listing 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?

Explicitly names the predecessor and trigger: 'Use after search_listings when the user wants to weigh companies against each other.' It gives a clear when-to-use and an alternative, though it does not state when not to use it or the behavior if listings are unapproved.

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 behavioral value by specifying the content of the report (tier, trial state, tool/field availability), which matters because there is no output schema to fall back on.

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

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

Two sentences, both earning their place: the first defines the returned content, the second states the trigger. No filler, and the purpose 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?

A parameterless, read-only diagnostic with no output schema, so the description must carry the return-value burden — and it does by enumerating what is reported. It stops short of describing format or how 'available fields' are surfaced, which is a small residual 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 there is nothing for the description to document; baseline for a parameterless tool is 4. The description correctly does not invent 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 (report) and resource (this FirmLedger connection's capabilities) and enumerates exactly what is reported: access tier, auth/trial status, available tools and fields. No sibling tool does anything similar, so differentiation is implicit and clear.

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

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

Gives a concrete trigger condition — 'Use when the user asks why something is locked' — which is exactly the diagnostic context an agent needs. It does not name alternatives or state exclusions, but no sibling tool overlaps, so the omission is minor.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds a real behavioral constraint: the user must confirm the exact subject and message before submission. It doesn't describe what happens on success (e.g., a ticket identifier or confirmation), but the two-step nature of the call is at least surfaced.

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

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

Three short sentences, front-loaded with the action and scoped by category list, then the confirmation precondition. The category enumeration partially duplicates the schema enum, but it reads as a deliberate routing aid rather than padding.

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

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

For a non-idempotent write tool with no output schema and 50% parameter coverage, the description supplies the key missing context: the confirmation gate and the valid category set. The two-step token mechanics live in the schema, so silence on return values is acceptable, though success behavior 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 50%; body and confirmation_token carry schema descriptions while subject and category do not. The description re-lists the category enum (redundant with the schema) and implies subject/message fidelity matters for confirmation, which adds modest meaning but not enough to compensate for the undocumented subject constraints.

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 ('Open a FirmLedger support ticket') with the target user, and enumerates the categories, which distinguishes it from sibling read tools like list_my_tickets. It stops short of explicitly contrasting itself with any sibling, so it's 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?

Provides one clear precondition ('Requires the user's confirmation of the exact subject and message'), which tells the agent not to fire blindly. However, it never says when to prefer this over siblings such as reply_to_lead or list_my_tickets, nor when not to open a ticket.

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

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

Annotations cover safety (readOnly=false, openWorld=true, idempotent=false, destructive=false), but the description adds behavior annotations cannot express: the two-step confirmation flow, the plan/scope prerequisites, and the one-time signing-secret disclosure. That one-time secret warning is genuinely useful operational 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?

Four short sentences, front-loaded with the confirmation requirement and the outcome before the prerequisites. Each sentence carries distinct information (what it does, prerequisites, secret handling), with only slight redundancy around the event destination.

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 5-parameter mutation with no output schema, the description covers the confirmation protocol, auth/plan requirements, and secret handling – the high-risk aspects. It falls short only on minor parameter semantics for label/categories, which is a modest gap rather than a blocking one.

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

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

Schema description coverage is only 40%, and the description fills in some of the gap by confirming that events are delivered to the URL and that a signing secret is issued. However, it says nothing about 'label' or 'categories', leaving two parameters undocumented in both places.

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

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

The description gives a specific verb+resource ('Register a webhook on the user's account') plus the effect ('Listing events will be sent to this URL'), so the agent immediately knows what the tool creates and where the payloads go. It does not need sibling differentiation because no sibling tool touches webhooks.

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 gating conditions clearly: explicit user confirmation, Pro (including free trial), and the write:account scope. It does not discuss when to prefer an alternative, but there is no plausible alternative in the sibling list, so the context is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely new behavior detail by disclosing the return is CSV text with a fixed column set (name, category, type, tech stack, verified owner, confidence, watched since), which tells the agent what it will actually receive.

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

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

One front-loaded sentence with no filler; the parenthetical column list is long but earns its place because no output schema exists to convey the return shape. Nothing is repeated from the annotations.

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

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

With no output schema, the description must carry the return contract, and it does by listing the CSV columns and likening it to the dashboard export. Minor gap: it doesn't say whether the value is a raw CSV string versus a file URL, which matters for consumption.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to compensate for. The column enumeration is output-related rather than parameter-related and does not create ambiguity.

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+format: the user's watchlist rendered as CSV text, and enumerates the columns produced. It doesn't explicitly name the sibling get_watchlist as the non-CSV alternative, so the differentiation from that sibling is left implicit.

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

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

The phrase 'the same file as the dashboard's Export button' gives the agent a mental model and implies usage (exporting rather than reading), but it never states when to prefer this over get_watchlist or whether any preconditions exist. Usage is inferred, not specified.

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 closed-world, so the safety profile is covered. The description adds real value by disclosing the payload contents (views by window, unique visitors, funnel, top locations) even though no output schema exists, giving the agent a behavioral sense of what it returns.

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

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

One dense, front-loaded sentence plus a short Dashboard-equivalence note; the metric list is enumerated efficiently with no filler. Slightly list-heavy but every item 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 enumeration of returned metrics carries the burden of describing results and does so thoroughly. It could go slightly further on data freshness/granularity, but for a read-only, single-optional-param tool it is essentially 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 coverage is 100% and the single 'listing' parameter is fully documented there, including the 'omit for all combined' semantics. The description adds nothing about the parameter, so the baseline 3 for schema-driven semantics applies.

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

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

The description names a specific verb (read) plus a precise resource (audience analytics for the user's own listings) and enumerates the exact metrics returned. No sibling in the tool list produces audience-analytics data, so the agent can distinguish it without opening any schema.

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

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

Usage is implied by 'the user's own listings' and the Dashboard mapping, which tells the agent this is a self-scoped reporting tool. However, there is no explicit when-to-use/when-not statement or routing to an alternative (e.g. compare_listings for cross-listing analysis).

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds genuine behavioral context beyond that: it explains that the MCP connector and REST API v1 are one platform entitlement and states what happens to API and MCP access when a free trial ends.

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

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

The purpose is front-loaded, but the second half is a long run-on sentence with repeated framing ('one account, one key, one Pro entitlement') that reads as promotional rather than informational. It earns its place only partially.

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 conveying return content, and it does so thoroughly, including entitlement/trial-end behavior. Nothing critical for correct invocation appears missing, though it never ties the key_prefix parameter to the filtering behavior.

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

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

Schema description coverage is 100% and the single optional key_prefix is fully documented in the schema, so the baseline is 3. The description never mentions key_prefix or the scoping behavior of focusing on one key, adding nothing over 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 ('The state of the FirmLedger REST API for this account and API key') and enumerates the payload it returns (identity, plan, scopes, budgets, usage, endpoint catalogue). However, it never names or contrasts with plausible siblings such as list_api_keys or manage_api_keys, so the agent must infer the distinction.

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 call this versus list_api_keys or manage_api_keys, no prerequisites, and no exclusions. Usage is only implied by the description of what the payload contains.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds meaningful behavioral context beyond that: it reveals the classification scheme it reports and that token expiry is surfaced, which helps an agent interpret the result. It does not discuss auth prerequisites for the call itself.

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

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

Two sentences, no filler, and the primary subject (how the connection is classified) is front-loaded ahead of the usage trigger. Every clause — connection modes, plan/trial state, tool availability, token expiry, and the when-to-use rule — 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 carries the burden of return-value disclosure and does so well: it lists the connection modes and the specific status fields (Free/Pro, trial, tools and fields, token expiry). Combined with annotations covering safety, an agent has everything needed to call and interpret 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?

The tool takes zero parameters, so the baseline is 4 under the rubric. There is no argument surface for the description to clarify, and the empty schema is consistent with the description's read-only, no-input framing.

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 (reports how the assistant is connected to FirmLedger) and enumerates the connection modes (public, API key, OAuth) plus the state it surfaces (plan, trial, available tools/fields, token expiry). An agent can tell what this returns without opening any schema, and the scope is distinct from the many list/manage 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?

Explicitly names the trigger conditions: when the member asks whether they are connected/signed in, or why something is locked. It stops short of naming alternatives or exclusions, which matters here because the near-identical sibling 'connection_status' is not differentiated, leaving a possible routing ambiguity unaddressed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the result contains the inquirer's details plus every message in oldest-first order, which tells the agent what a call actually yields.

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

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

Two sentences, both front-loaded and purposeful: the first states content and ordering, the second states when to call it. Nothing is wasted or redundant.

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

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

With no output schema, the description compensates by describing the return content (inquirer details, all messages, oldest first) and the call context. For a single-parameter read tool with full annotation coverage, nothing an agent needs is missing.

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

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

Schema coverage is 100% and the single parameter lead_id is documented in the schema as coming from list_leads. The description adds no syntax, format, or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific resource and scope: 'One conversation from the Leads inbox with the inquirer's details and every message, oldest first.' This is clearly a single-item read, implicitly distinguished from the list_leads sibling, though it never names that sibling to make the contrast 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?

It gives explicit usage context: 'Use before reply_to_lead so the reply fits the thread,' tying the tool to a concrete downstream workflow and naming reply_to_lead. There are no when-not conditions or stated alternatives, but the sequencing guidance is 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 cover read-only, idempotent and non-destructive, so the bar is lower. The description adds genuinely useful behavioral context beyond them: which fields are always public versus which require FirmLedger Pro (website, email, phone, key people, timeline, technology), letting an agent anticipate absent 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?

One sentence, front-loaded with the core action and resource, followed by a field enumeration. The list is dense but every clause maps to real returned content; it could be trimmed slightly but nothing is padded or repetitive.

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

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

With no output schema, the description carries the burden of describing returns, and it does so thoroughly, including the plan-dependent split. The one remaining gap is error behavior for an unresolvable or ambiguous identifier, which the description never addresses.

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

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

Only one parameter and schema description coverage is 100%, so the schema fully documents the accepted identifier forms (slug, exact name, FL-00012 ID, profile URL). The description adds nothing about the listing argument, so the baseline 3 applies.

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

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

States a specific verb+resource: fetches the public FirmLedger profile of one company, with an enumerated field list (verification state, scores, news, jobs). The phrase 'of one company' implicitly distinguishes it from search_listings, but no sibling is named in the description 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 explicit when-to-use or when-not guidance. The agent must infer that this is the lookup step after search_listings returns a slug, and nothing routes it away from close siblings like get_lead, get_my_listings, or compare_listings.

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

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

Annotations already declare this a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds genuine behavioral value by enumerating the returned payload — moderation status, tick, scores, Pro perks, sponsorship, jobs and new-lead counts — which tells the agent what it will actually receive.

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

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

Two sentences, both front-loaded: the returned scope and payload come first, then the routing hint. No filler, no repetition of the title or annotations.

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

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

With no parameters, no output schema and full annotation coverage, the only real gap is the return shape — and the description compensates by listing the returned fields. Pagination and ordering behavior are unstated but minor for an owner-scoped list.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It uses the space instead to describe the output fields, which is a sensible use of a parameter-free 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 resource plus its exact scope — listings 'this account owns or submitted' — which is precisely what separates it from get_listing and search_listings. It does not explicitly name the sibling tools it differs from, 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?

'Use first when the user refers to "my listing"' gives a clear trigger condition with an implied priority over alternatives. It lacks an explicit when-not clause (e.g. use get_listing for a single listing by id), so routing still requires a little inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, so safety is covered. The description adds real value by disclosing that content is 'moderated' and 'accuracy-gated' and gated behind the Pro plan, but says nothing about caching, freshness/latency, or rate limits for a news-fetch tool.

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

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

Two compact fragments with the plan qualifier front-loaded and no filler. Every clause adds information about scope or content, though the em-dash clause could be trimmed 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?

With no output schema, the description helpfully enumerates the returned fields (headlines, dates, publishers, links), so an agent knows what to expect. The remaining gap is the absence of guidance on result ordering or empty-result behavior, which is minor for a 2-param read tool.

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

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

Schema description coverage is 100%, so both parameters (listing identifier formats, limit range/clamping) are fully documented in the schema. The description adds no parameter-level detail beyond that, making the baseline 3 appropriate.

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

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

States a clear verb+resource: recent moderated news headlines for one company, with the returned fields (dates, publishers, links) named. It is distinguishable from get_listing and refresh_listing_news by scoping to headlines only, though it does not explicitly name a sibling to contrast against.

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 'about one company' phrasing implies single-listing scope and the Pro tag implies a plan prerequisite, but there is no explicit when-to-use guidance and no mention of when to prefer refresh_listing_news or get_listing instead. Usage is only inferable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: results are ordered newest-first and the response carries an unread count, 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?

Two short sentences, nothing wasted, and the resource plus ordering are front-loaded before the parameter hint.

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 shape (notifications plus unread count), but for a 2-parameter tool with 0% schema coverage the unexplained limit parameter and absence of any pagination or when-to-use guidance leave real gaps.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It explains unread_only's meaning but says nothing about limit (range 1-60, default 20) or result truncation behavior, leaving one of two parameters undocumented.

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

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

The description names a specific resource (the user's in-app FirmLedger notifications) and its ordering (newest first) plus the included unread count, which clearly separates it from the mutating sibling mark_notifications_read. It never names that sibling explicitly, so it stops short of full sibling differentiation.

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

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

"Set unread_only for just the unread ones" implies when to toggle the flag, but there is no guidance on when to call this tool versus mark_notifications_read or other siblings, and no mention of pagination or limits.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and idempotency are covered. The description adds genuinely new behavioral context: coverage is limited to relationships recorded by the verified owner or moderators and nothing is inferred, which tells the agent about data provenance and the possibility of empty or incomplete graphs.

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 tier marker is front-loaded, followed by one dense sentence covering scope, edge types and provenance. Every clause earns its place, though the enumeration-heavy sentence is long and 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?

There is no output schema, and the description compensates by describing the returned graph contents in both directions (owned edges and reverse edges). Combined with a fully documented required parameter and annotation-covered safety profile, nothing an agent needs in order to call this correctly is missing.

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

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

Schema description coverage is 100%, and the schema fully documents the single 'listing' parameter (slug, exact name, FL-ID, or profile URL). The description adds no syntax or format guidance beyond that, so the baseline 3 is correct.

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+resource ('the recorded relationship graph of one company') and enumerates exactly what is included: founders, investors, parent companies, subsidiaries, products, services, partners, plus reverse edges. An agent can distinguish this from get_listing or compare_listings without inspecting either schema.

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

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

Usage is implied by the scope statement rather than stated: the agent can infer it should be called when a relationship graph is needed, and the 'Pro' marker signals a tier gate. However, no sibling is named as an alternative and there is no explicit when/when-not condition, so this stays at the implied-usage level.

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's only added behavioral detail is the sort order ('newest first'), which is genuinely useful but thin; it says nothing about pagination, list size, or whether entries include scores/news.

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

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

A single short sentence with no filler, and the identifying detail (whose companies) is front-loaded ahead of the ordering qualifier.

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 parameterless read tool with no output schema, the definition conveys what the list is and how it is ordered, which is close to sufficient. It stops short of describing what a watchlist entry contains, so an agent cannot predict the response shape.

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

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

The tool takes zero parameters, establishing the baseline of 4. The description adds nothing further on inputs, which is appropriate since none 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?

The phrase 'The companies the user watches on FirmLedger' names the exact resource being read and adds the ordering ('newest first'), so an agent knows what comes back. It is a noun phrase rather than an explicit verb+resource, and it never distinguishes itself from siblings like export_watchlist_csv or watchlist_add/remove.

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

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

There is no guidance on when to call this versus export_watchlist_csv (which also surfaces watchlist data) or the watchlist_add/watchlist_remove mutators. The read-only intent is left entirely 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 carry readOnlyHint/idempotentHint/non-destructive/closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: results are conditional on authentication ('With an API key it also lists the user's own listings and which of them can be advertised or are already sponsored'), which the agent could not infer 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?

Two tight sentences with no filler; the identity of the data set is front-loaded and the workflow hint comes last. Every clause earns its place.

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

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

With no output schema, the description must convey the return shape, and it does name the fields (price, billing, duration) and the auth-conditional extra data. It omits any note on pagination, ordering, or empty-result behavior, which for a list tool is a minor but real 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?

There are zero parameters, so the baseline is 4 by rule; the schema is empty and additionalProperties=false. The description's mention of an API key explains an implicit ambient input (auth) that changes the response, adding a bit of value even without 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 the resource precisely ('Sponsored-placement advertising packages') plus the attributes returned (price, billing, duration). The verb is implied by the name/title rather than stated, and it doesn't explicitly contrast with siblings like list_plans or get_my_listings, which keeps it just short of a 5.

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

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

"Use before prepare_advertising" gives an explicit ordering and names the sibling it precedes, so the agent knows the workflow context. It does not state when NOT to use it or what alternative to prefer if the agent only wants the user's own listings, so it falls short of 5.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the response never contains a raw secret key, so the agent knows it cannot retrieve credential material here. It doesn't mention pagination or ordering, but for a small key list that is minor.

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 clauses: what is returned, then when to use it. Front-loaded with the resource and the security-relevant 'never a raw key' caveat, with no filler.

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

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

With no output schema, the description carries the return-value burden and does so by listing label, prefix, scopes, usage totals and last use. What is missing is only secondary: ordering, pagination, and whether the list is scoped to the calling user or the whole account (the title says 'my', the description says 'the account's', a slight ambiguity).

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

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

The tool takes zero parameters and the schema coverage is complete, so the baseline is 4 and there is nothing for the description to clarify. The field inventory it provides describes output, not inputs, which is the right place given the empty 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?

Names the resource precisely (the account's API keys) and enumerates the returned fields, so an agent knows exactly what this yields. It does not explicitly contrast with the near-name sibling manage_api_keys or get_api_status, so sibling differentiation is only implied by the 'before revoking or re-scoping' hint.

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

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

Gives a concrete when-to-use scenario: call it to identify/name a key before revoking or re-scoping it, which implicitly points at the mutation sibling. It states no exclusions or edge conditions, and does not say what to do if no keys exist or which tool handles the revoke itself.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered; the description adds the return content (categories plus approved-listing counts), which is real behavioral value 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?

Two short sentences with no waste; the result shape is front-loaded and the usage hint follows immediately.

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

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

For a zero-param lookup with no output schema, the description supplies what the tool returns and why to call it. Only the exact result ordering/format is unspecified, which is minor.

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

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

Zero parameters, so there is nothing to document; the schema is trivially complete. Baseline for a parameterless tool is 4.

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

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

States a clear verb+resource (list every firm category) and its payload (number of approved listings). It is distinguishable from the other list_* siblings by resource, though it doesn't explicitly contrast with them.

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

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

Explicitly states the use case: pick a valid category before calling search_listings, naming the sibling it feeds. No when-not guidance, but the intended moment of use is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so safety is covered. The description adds return-shape context (per-country approved-listing counts), which is useful given there is no output schema, but it says nothing about ordering, pagination, or 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?

A single dense sentence with zero filler, front-loading the resource and the returned payload. 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?

For a zero-parameter enumeration tool with annotations covering safety and no output schema, the description carries the necessary return-value detail. It is nearly complete, missing only ordering/pagination behavior.

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 for 0 params is 4. The description correctly implies an unfiltered full enumeration.

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

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

States the specific resource (countries in the FirmLedger directory) and what each item carries (number of approved listings). An agent can tell this apart from list_categories or list_plans by resource. It does not name or contrast any sibling explicitly, so it stops short of 5.

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

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

Gives no when-to-use context, no prerequisites, and no mention of alternatives among the many list_* siblings. The purpose is inferable but usage guidance is absent.

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 and the closed-world profile. The description adds real context beyond that: Pro-tier gating and the guarantee that unapproved listings never surface, which is exactly the kind of filtering behavior an agent should know.

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?

Essentially two compact sentences with the tier gate and filter set front-loaded and no filler. The 'FirmLedger Pro.' fragment is slightly clipped but costs almost nothing.

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

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

With no output schema, the description compensates by naming the returned fields and the approval filter, and annotations cover safety. Pagination limits live in the schema, so nothing essential is missing for an agent to call this correctly.

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

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

Schema coverage is 100%, so each of the five parameters is already documented in the schema, and the description only restates the filter dimensions (company, location, keyword). It adds the returned field list, which is useful given there is no output schema, but that is completeness rather than parameter semantics.

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

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

Clear verb ('List') plus resource ('open jobs') and explicit scope: filtered by company, location, and keyword, with the returned field set named. It does not name a sibling tool as the alternative (e.g. manage_job or post_job), so it stops short of a 5.

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

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

The description implies browsing open roles at approved companies, but never says when to use this versus manage_job, post_job, or search_listings. The only routable condition given is the approval filter, which is a data constraint rather than a usage guide.

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-destructiveHint and closed-world, so the safety profile is covered. The description adds that results are paginated, which is genuine extra context, but it says nothing about ordering, page-size limits, or what happens at the end of the result set.

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

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

A single dense sentence front-loads the resource definition and tucks the box options and filtering into parenthetical clauses; nothing is wasted. It borders on crowded, which keeps it from a 5, but the structure is efficient.

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

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

For a 5-parameter list tool with no output schema and low schema coverage, the description covers box selection, filtering and pagination, which is the core. It still omits the status enum values, paging defaults/limits, and result ordering, so an agent cannot fully predict the parameters or the return shape from the description alone.

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 20% (just the listing param), so the description does real work: it names the three box values, marks 'received' as the default, and describes status/listing filtering. But it never enumerates the status values (new/contacted/qualified/won/lost) or explains page/limit defaults, leaving the low-coverage schema only partially compensated.

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 (leads), then defines what a lead is ('inquiries received on their listings') and enumerates the three inboxes. This is far more than a restatement of the title. It doesn't explicitly contrast itself with the sibling get_lead (single lead) or set_lead_status, so it stops short of a 5.

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

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

The description gives useful context that 'received' is the default box and that results can be filtered by status or listing, which implies the normal usage pattern. However, it never says when to reach for this tool versus siblings like get_lead, search_listings, or list_my_tickets, and there are no exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: the tool switches modes based on whether a ticket reference is supplied, and that supplying one returns the full conversation rather than just metadata. It still omits pagination and result ordering, but the mode-switch disclosure is real added value.

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

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

Two short sentences, front-loaded with the resource and followed immediately by the parameter behavior. There is no filler or redundancy.

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

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

With annotations covering safety and a simple single-optional-parameter schema, the description is minimally adequate. It never states what the listing (no-parameter) mode returns, whether there is pagination or a result cap, so the description is slightly thin for a list tool with 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 100% and the schema already documents the 'ticket' parameter with an example ('TK-1A2B3C'). The description goes beyond the schema by explaining the consequence of passing it — reading that ticket's full conversation — which the schema alone does not convey.

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

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

The description names the specific resource (the user's FirmLedger support tickets) and implies the list/read behavior, with the name and title supplying the verb. It is clear enough to distinguish from create_support_ticket, but there is no explicit differentiation from other sibling read tools.

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

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

It gives one concrete usage instruction ('Pass a ticket reference to read that ticket's full conversation'), which implies dual-mode behavior (no param = list, param = read one). However, there is no explicit guidance on when to use this versus alternatives, nor any prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds conditional behavior beyond the schema: with an API key it also reports whether the account is already on Pro and whether a free trial is available, which is genuinely useful context for an agent.

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

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

Two tightly written sentences with no filler, front-loading what is listed and then layering the conditional behavior and the sequencing advice.

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 burden of describing returns, and it does so reasonably: price, billing, duration, Pro status, and trial availability. A bit more on the shape/format of plans would make it fully complete.

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

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

Zero parameters, so the baseline is 4. The description's note about API-key-dependent account status is the only parameter-adjacent nuance, and it correctly implies no required 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?

The description states the specific resource and its contents: current Pro plans with price, billing, and duration. It's clear this is a read/list operation on the plans catalog, though it never uses an explicit verb like 'lists' and doesn't differentiate itself from sibling list_* tools beyond the resource name.

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

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

'Use before prepare_upgrade' gives explicit sequencing guidance naming the downstream sibling tool. There is no when-not guidance or statement of alternatives, but the intended call point is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral value beyond that: it discloses exactly what data comes back (events, category filters, active state, signing-secret prefix) and that delivery history appears only in the id-scoped mode.

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

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

A single dense sentence with the primary scope front-loaded and the conditional mode appended. Efficient, though the field enumeration makes it somewhat list-heavy for one sentence.

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

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

With no output schema, the description correctly carries the burden of describing return content, and it does so at both levels (destination list and delivery records). Combined with complete annotation coverage for a read-only tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 50%: webhook_id is documented in the schema and the description reinforces its meaning (it switches the tool into recent-deliveries mode). The limit parameter is undocumented in both schema and description, and the description adds no syntax or range guidance for it.

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

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

Names the resource (the account's webhook destinations) and enumerates the payload fields returned, making the verb effectively 'list with optional detail drill-down'. It is distinguishable from create_webhook/manage_webhooks, though it never names them explicitly.

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

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

The conditional 'when a webhook id is given' implies two modes of use (overview vs single-destination with deliveries), which is useful implied guidance. However, there is no explicit statement of when to choose this over manage_webhooks or create_webhook, and no prerequisites or exclusions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior the annotations don't: the raw key is returned only once at creation, and the operation is gated on user confirmation.

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

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

A single dense paragraph that front-loads the three actions, then the confirmation prerequisite, then the scope nuance. No filler, though the confirmation mechanism is restated from the confirmation_token schema 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 non-idempotent, destructive, multi-action tool with no output schema, the description covers the confirmation gate, the one-time raw key disclosure, and the scope model. It could say more about revoke permanence or scope-change effects on existing integrations, but the essentials 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 description coverage is already 83%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that keys can carry the AI-assistant scopes (read:account / write:account) used by this connector, which explains why those enum values 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?

The description names the resource (API keys) and enumerates the three concrete operations — create, revoke, change scopes — mapping directly to the action enum. It also implicitly separates itself from list_api_keys by framing the tool as the mutating counterpart to that listing 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?

It gives a clear usage condition — the mutation requires the user's explicit confirmation — and contextualizes the tool as the dashboard's Developer API controls. It stops short of explicitly routing the agent to list_api_keys first to obtain key_id, leaving that inference to the schema description.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds a genuinely non-obvious side effect: editing a live or closed role sends it back through moderation before it becomes public again. It also flags the user-confirmation requirement, which is essential context for a destructive mutation.

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 operation list, followed by the two highest-value caveats (moderation re-review, confirmation requirement). Three tight sentences with no filler; the enumeration is dense but each item maps to a real capability.

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 multi-action tool with no output schema, the description covers scope, mutation side effects, and the confirmation gate, and the schema details the confirmation_token handshake. It stops short of explaining what each action returns or whether close vs delete differ in reversibility.

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 13% (just confirmation_token), so the description must compensate. It lists the editable fields (title, type, location, apply link, description), mapping loosely onto title/role_type/location/apply_url/description, but gives no format, length, or action-to-field mapping detail that the bare schema lacks.

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

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

Names a specific resource (a job owned by the member) and enumerates the exact operations: edit title/type/location/apply link/description, close, or permanently remove. An agent can separate this from post_job (creation) and update_my_listing without opening the schema.

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

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

It scopes the tool to jobs the member owns and implicitly contrasts edit vs close vs remove, but it never names an alternative tool or states when-not to use it (e.g., use update_my_listing for listing edits). The confirmation prerequisite is stated, but that is a procedure rather than usage 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 destructiveHint=true, readOnlyHint=false, and non-idempotency; the description adds that deletion is irreversible and that user confirmation is required, which is meaningful context beyond the structured hints. It does not, however, detail the two-step token handshake itself, which lives in the schema.

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

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

A single front-loaded sentence names the three actions first and appends only the essential constraint (confirmation, irreversibility). No filler, and the most decision-relevant information leads.

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 three-action tool with no output schema, the description covers the destructive nature, irreversibility, and confirmation requirement. The confirmation mechanism details are carried by the schema, so nothing critical is missing, though it could note which action the confirmation applies to.

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 67%: action, lead_id, and confirmation_token are all documented in the schema, including the first-call/second-call token protocol. The description adds no parameter-level detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description names specific verbs (archive, restore, delete) and a precise resource (a lead conversation), and characterizes the scope as 'the dashboard's conversation controls.' An agent can clearly separate this mutation tool from siblings like get_lead, list_leads, or reply_to_lead.

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 establishes the context (business inbox conversation management) and the prerequisite of user confirmation, which is the key gate for invoking it. It stops short of explicitly naming alternative tools or stating when not to use it, so it is clear but not fully 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 destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the general risk profile is covered. The description adds genuinely non-redundant behavior: secrets are returned only for create and rotate, and the operation requires the user's confirmation. It still does not say what delete destroys or whether any operation is reversible.

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

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

A single front-loaded sentence lists the operations first, then the two most important behavioral notes (secret exposure, confirmation). It is dense but every clause carries information; slight readability cost comes from the long comma-separated action list.

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

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

With no output schema and a destructive 8-parameter tool, the description does enough: it covers the confirmation handshake, secret return scope, and full action set. Missing details are what delete removes and any delivery-listing behavior, but an agent can call the tool correctly from what is given.

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 63% with 8 parameters, so the schema documents most of the semantics (url, events, webhook_id, delivery_id, confirmation_token). The description adds only the create/rotate secret behavior and does not clarify the undocumented label or categories parameters, so it neither compensates for the gap nor falls below the 3 baseline.

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

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

The description names a concrete resource (webhook destination) and enumerates the exact operations it performs (create, update, pause, resume, rotate_secret, test, retry_delivery, delete), which matches the action enum precisely. The only gap is that it does not differentiate itself from the sibling create_webhook, so an agent cannot tell from the text alone which tool to pick for creation.

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 anchors usage to a known surface ('the same operations as Dashboard → Developer API') and flags the confirmation requirement, which implies when it is appropriate. However, it never states when NOT to use it or how it relates to create_webhook/list_webhooks, leaving the create path ambiguous across 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 declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the non-obvious behavioral requirement that user confirmation is needed, complementing the confirmation_token workflow documented in the schema.

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

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

Two tight sentences with zero filler; the two operational modes are front-loaded and the confirmation prerequisite follows. Every clause earns its place.

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

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

For a mutation tool with no output schema, the description covers scope selection and the confirmation prerequisite, and the schema details the token round-trip. It stops short of describing what happens to already-read notifications or what the confirmation summary contains.

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% (only confirmation_token is annotated), so the description must compensate. It does explain the meaning of notification_id and the all: true switch, but adds no format, bounds, or mutual-exclusion semantics beyond what the parameter names imply.

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

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

States a specific verb and resource ('Mark ... as read') and enumerates both scopes: a single notification via notification_id or the whole set via all: true. An agent can immediately tell this apart from the read-oriented get_notifications sibling.

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

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

The description signals both invocation modes and states the precondition that the user's confirmation is required, which is the key gate for this tool. It does not, however, mention any when-not conditions or compare itself to siblings like get_notifications.

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

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

Annotations only cover safety flags (readOnly=false, destructive=false, idempotent=false, openWorld=true), so the description carries meaningful extra burden and delivers: moderation queueing, delayed publication, Pro-perk eligibility, role-count limits, and the confirmation requirement. This is real behavioral context an agent cannot get 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 dense sentences, eligibility and workflow front-loaded, zero filler. The 'Like the dashboard form' analogy efficiently conveys behavior without extra words.

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

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

For a non-idempotent mutation with no output schema and a confirmation flow documented in the schema, the description covers prerequisites, moderation lifecycle, and limits. It omits what happens on rejection or any failure modes, but nothing critical to calling correctly is missing.

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

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

Schema coverage is 57%, so some parameters (title, role_type, description) have no textual description anywhere. The description adds valuable eligibility context about the 'listing' parameter (must be the user's own, needs Pro perks), but says nothing about role_type or the other bare fields. Adequate but with a visible 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: 'Submit a job opening on one of the user's listings.' This is clearly distinct from the read-only sibling list_jobs. It does not explicitly name an alternative, but the action 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?

Gives concrete preconditions (active Pro perks on the listing, max 5 open/pending roles) and the workflow (moderation first, published after approval, user confirmation required). It stops short of naming alternatives or when-not-to-use cases, but the eligibility constraints guide the agent well.

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/idempotent/non-destructive, but the description adds genuinely new behavior context: no charge occurs, the user pays on FirmLedger's own checkout, and the agent can never complete or confirm a payment. This resolves the misleading "checkout" wording that annotations alone would not.

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 critical "Does NOT charge anything" disclaimer, and each sentence carries distinct information (validation, payment boundary, re-issue instruction). No waste.

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 tells the agent what is returned (a personal checkout link) and where payment happens. For a 2-param, fully-documented read-only tool, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description only restates context (user's own approved listing, chosen package) without adding syntax or format detail beyond it, so the baseline 3 applies.

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

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

The description states a specific verb-and-resource action: validating a listing and returning a personal FirmLedger checkout link for a Sponsored-placement package. It is clearly distinguishable from siblings like prepare_listing_claim or prepare_upgrade because it names the checkout/payment context explicitly.

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

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

It gives the precondition (listing must belong to this account and be approved), names the source tools for both parameters (get_my_listings, list_ad_packages), and handles the follow-up case: if the user says "yes, do it", return the link again rather than attempting payment.

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 real value beyond that: it is 'Free,' it 'Creates nothing and never grants ownership' (pre-empting a likely misconception), and it discloses the manual token/install/verify steps. Return format remains unspecified, keeping it from a 5.

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

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

Three tightly packed sentences, front-loaded: cost, purpose, negative scope, then the workflow. Every sentence earns its place with no filler or repetition 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 read-only preparation tool with no output schema, the description covers purpose, constraints and the follow-up verification workflow. It could say more about what the prepared link/token contains, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 50%: the `listing` param is well documented in the schema, but the `method` enum (dns/meta/badge) carries no schema description. The description compensates by naming the three proof mechanisms — 'DNS TXT, HTML meta tag or site badge' — giving the enum values concrete meaning, which is genuine added semantics.

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

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

States a specific verb and resource: 'Prepare a link to claim an approved listing using DNS TXT, HTML meta tag or site badge.' It also draws a sharp line around scope with 'Creates nothing and never grants ownership,' so the agent knows this is the preparation step, not the claim itself. It does not explicitly name a sibling (e.g. check_domain or prepare_listing_submission), so not 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?

Describes the flow an agent should expect: 'The user signs in, generates a token, installs the proof on the business domain and verifies it on FirmLedger.' This gives clear context for a multi-step human-driven workflow. It stops short of explicitly routing to alternatives (like a verification sibling) or naming when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the return artifact (a pre-filled link), the human-in-the-loop handoff, and the duplicate-listing check, all of which the annotations cannot convey.

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

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

Five tight sentences, front-loaded with the most important fact (no creation) and the return value. Every clause earns its place; nothing is redundant with the title or schema.

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

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

For a 5-parameter tool with full schema coverage, full annotations, and no output schema, the description is nearly complete: it covers purpose, workflow, and the duplicate-check behavior. It could optionally mention link expiry or auth prerequisites on the destination form, but nothing essential is missing.

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

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

Schema coverage is 100% and each parameter already carries a description, so the schema does the heavy lifting. The description only restates which fields are pre-filled (name, website, optional category/country/city), adding 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 ('prepare...listing submission link') and immediately negates the wrong mental model with 'Does NOT create anything.' This clearly separates it from sibling mutators like prepare_listing_claim, prepare_upgrade, and post_job, which is exactly the differentiation an agent needs.

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

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

The description explains the workflow – the tool returns a pre-filled link, the user signs in, completes the remaining fields and submits themselves – which tells the agent when this tool is the right call versus doing nothing. It does not explicitly name an alternative tool or when-not-to-use condition, so it stops short of a 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive, and closed-world behavior, but the description adds substantial operational context: it never charges, cannot complete or confirm payment, must never ask for card details, and returns the pricing page without an API key. These details go well beyond the structured annotations and are exactly what an agent needs to avoid misusing the tool.

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

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

The description is front-loaded with the most important constraint ('Does NOT charge anything') and then efficiently covers the return value, the user's payment flow, the payment-confirmation boundary, and the no-API-key fallback. Every sentence earns its place, and there is no redundant or 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?

Given two simple parameters, no output schema, and rich annotations, the description supplies the missing behavioral and return-context information an agent needs. It explains what the link is, what the user does with it, what the tool cannot do, and what happens without an API key. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, and both parameters are already documented in the schema: plan as the id or exact name from list_plans, and promo_code as an optional user-provided code. The description mentions the chosen Pro plan and optional promo code but adds no format, source, or validation detail beyond the schema, 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 description clearly states a specific action and resource: it returns a personal checkout link for the chosen FirmLedger Pro plan, optionally with a promo code. It also draws a sharp boundary by saying it does NOT charge anything. However, it does not explicitly differentiate this tool from sibling prepare_* tools, 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?

It gives clear contextual guidance: give the user the link so they can sign in and pay on Lemon Squeezy themselves, and if the user says 'yes, do it,' give the link again. It also states the no-API-key fallback of returning the pricing page. It does not name an alternative sibling tool or state when not to use this tool beyond the payment-boundary 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 cover the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false). The description adds value beyond them: the per-listing rate limit, the dashboard-consistent accuracy/moderation rules, and the mandatory user confirmation. Return/pagination behavior is still 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?

Front-loaded with the action, then the constraints and the confirmation requirement. Two dense but non-redundant sentences with no filler. Slightly heavy in one sentence structure but every clause earns its place.

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

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

For a non-read-only, non-destructive refresh with no output schema, the description covers purpose, rate limiting, moderation parity, and the confirmation gate. Missing only return-value shape, which is acceptable given there's no output schema.

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

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

Schema description coverage is 100%, so both parameters are already fully documented, including the confirmation_token flow. The description's confirmation note restates what the schema already says and adds no new syntax or format detail. Baseline 3 applies.

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

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

States a specific verb and resource: 'Look for new coverage of one of the user's approved listings.' An agent can distinguish it from get_news (read existing) and refresh_listing_scores/tech (other refresh targets). It stops short of naming siblings but the action 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?

Gives concrete usage context, the rate limit ('once a minute per listing') and the confirmation requirement, plus the dashboard parity reference. It doesn't explicitly contrast with get_news, so it falls short of a full when/when-not statement.

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

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

Annotations already declare it non-read-only, idempotent, and non-destructive. The description adds useful context beyond them: scores are recomputed 'from its current record' (no external fetch) and the operation requires explicit user confirmation before taking effect. The confirmation detail partially overlaps the schema's token explanation, keeping it from a 5.

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

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

Two tight sentences, purpose front-loaded with the score types, then the confirmation prerequisite. Every clause earns its place with no filler.

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

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

For a low-complexity two-parameter tool with no output schema, the definition covers purpose, data source, and the confirmation gate, and annotations cover the safety profile. It could have noted what the first call returns (action_summary/token) or that results are stable across repeats, but those gaps are minor.

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

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

Schema description coverage is 100%, so both 'listing' and 'confirmation_token' are already documented in the schema. The description repeats the ownership constraint ('one of the user's listings') but adds no format, syntax, or edge-case detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb ('Recompute') and resource ('confidence, health and completeness scores of one of the user's listings') and ties it to the dashboard label 'Re-align scores', which clearly separates it from refresh_listing_news and refresh_listing_tech. It stops short of naming or contrasting those siblings explicitly, so it misses the top band.

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 prerequisite 'Requires the user's confirmation' is stated, and the schema documents the two-step confirmation flow. However, there is no guidance on when this tool is preferable to alternatives like refresh_listing_news/tech or the other prepare_* siblings, leaving usage context implied rather than explicit.

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

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

Annotations declare the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower; the description adds the confirmation-gated workflow, which is genuinely non-obvious behavior. It does not spell out that an external scan is performed against the open web, which the annotation implies but the text leaves implicit.

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 tightly packed sentence plus a short clause, with the action and its precondition front-loaded. No filler, no redundancy with 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 two-step, confirmation-gated mutation with no output schema, the description conveys the action and the confirmation gate, and the schema covers the token mechanics. It could be slightly richer about what the refresh actually changes, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and both parameters, including the confirmation_token two-step flow, are fully documented in the schema. The description adds no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb+resource ('scan the website... refresh its technology snapshot') and pins the domain to technology, which cleanly separates it from siblings like refresh_listing_news and refresh_listing_scores. The dashboard-alias ('Refresh tech') reinforces the intent unambiguously.

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 (refreshing one of the user's own listings) and the key precondition ('Requires the user's confirmation'), including the two-step nature. It does not explicitly contrast with refresh_listing_scores/news when a user has multiple refresh options, so it stops short of full when/when-not guidance.

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

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

Goes well beyond the annotations: it discloses the external side effect ('the other party is notified'), the mandatory user-confirmation gate, and the exact first-call behavior (returns the message for approval rather than sending). Annotations only flag readOnly=false and openWorld=true, so this adds substantial 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?

Two tight sentences, zero waste. The core action and its side effect come first, and the confirmation requirement follows immediately, so the agent gets the critical behavioral constraint up front.

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

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

For a mutation tool with no output schema, the description covers the key risks: external notification and the required confirmation handshake. Minor gaps remain (error behavior, whether retries are safe given idempotentHint=false), but nothing essential to correct invocation is missing.

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

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

Schema coverage is 67%, with confirmation_token already well documented in the schema. The description reinforces the flow semantics ('the first call returns the exact message for them to approve'), clarifying why the token exists and how it relates to user approval, adding meaning beyond the raw parameter list.

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

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

States a specific verb and resource ('Send a reply in one of the user's lead conversations') and anchors it to the familiar website Reply box, which lets an agent distinguish it from siblings like get_lead, list_leads, and set_lead_status.

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

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

The description conveys that the reply must be user-approved and describes the two-call flow, which implies when to invoke it, but it never names an alternative tool or states when not to use this one (e.g., versus set_lead_status). Usage is implied rather than spelled out.

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

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

Annotations already declare it as a non-read-only, non-destructive, non-idempotent, open-world write. The description adds behavior the annotations cannot express: the reply goes to a real support thread an agent answers, closed tickets are rejected, and the user must confirm the exact text before it is sent. It does not describe any rate limits or error responses, keeping it short of a 5.

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

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

Three tight sentences, front-loaded with the action and scope, then constraints. No filler, and the confirmation requirement is placed where it will be read 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 3-param write tool with no output schema, the description covers scope, the open-ticket precondition, and the confirmation dance, which is the essential procedural context. It omits any hint of what the caller receives on success (beyond the token step), a minor gap given annotations already signal the mutation profile.

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 field-level meaning of ticket, message, and confirmation_token is already documented. The description still adds cross-parameter semantics by stating the confirmation requirement up front, which frames the two-call token pattern as a user-approval step rather than just a technical field.

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

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

Specific verb+resource ('Send a reply in one of the user's own support tickets') with explicit scope ('the user's own') that separates it from reply_to_lead, create_support_ticket, and list_my_tickets. The clarification that it writes into the same thread the dashboard shows pins down what the action actually affects.

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

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

Gives a clear when-not condition ('Closed tickets cannot take replies') and a precondition ('Requires the user's confirmation of the exact text'), reinforced by the schema's confirmation_token flow. It stops short of naming sibling tools or alternatives, so it is clear context rather than full routing guidance.

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

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

Annotations cover only the safety profile (readOnly=false, idempotent=true, destructive=false), while the description adds genuinely new behavior: the browser hand-off, that the member approves there, that no password or key transits the chat, and that refresh implies a retry. These are the operational facts an agent needs for an auth flow and they are 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 correctly: purpose, then triggers, then the flow, then mode semantics. It is slightly redundant in re-stating the three mode descriptions that already live verbatim in the schema, which is the only reason it isn't a 5.

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

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

For a 1-parameter, zero-required mutation tool with no output schema, the description is nearly complete: flow, triggers, mode effects and post-refresh retry are all present. It stops short of describing what success or failure looks like to the caller (e.g., whether the connection is then active for subsequent calls), which it could state since no output schema exists.

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

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

Schema coverage is 100% and the enum description already restates each mode, so the baseline is 3. The description adds a small amount beyond the schema — 'connect (the default) starts sign-in when the connection needs it' and the retry instruction for refresh — which is meaningful but largely overlaps the enum text.

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 ('Connect this assistant to the member's own FirmLedger account by sign-in (OAuth), or renew or replace that connection') and scopes it against siblings like revoke_connection and connection_status by naming the three modes. An agent can distinguish this from the status/revoke siblings without opening any schema.

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

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

It gives explicit trigger phrases ('connect me to my account', 'sign me in', 'switch accounts') plus a per-mode selection rule: connect when the connection needs it, reauthenticate to end the current connection and re-choose an account, refresh for an about-to-expire token followed by a retry. That is when-to-use and which-alternative guidance in one place.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds real behavioral context beyond them: the request is deferred, nothing is removed until a moderator accepts, and user confirmation is required. It doesn't state irreversibility, rate limits, or failure modes, keeping it from a 5.

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

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

Three short sentences, front-loaded with the action and scope, then the review gate, then the confirmation constraint. Every sentence carries distinct information with no waste.

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 tool with no output schema, the description covers the key agent-relevant facts: scope, deferral, moderator gate, and confirmation requirement. It omits what the moderator rejection looks like and whether re-requesting is possible, a minor gap.

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

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

Schema description coverage is 100%, so baseline is 3; the descriptions of 'reason', 'listing', and the two-step confirmation_token flow are already fully documented in the schema. The description's 'Requires the user's confirmation' restates the confirmation flow rather than adding syntax or format detail, so no lift above baseline.

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

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

States a specific verb and resource ('Send a removal request for a listing') and scopes it to listings the user owns or originally submitted, which distinguishes it from the many listing-read/refresh siblings. It does not name a specific sibling tool as an alternative, 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?

Gives a clear condition for use ('a listing the user owns or originally submitted') and explains the moderator-review gate plus the confirmation prerequisite. It never points to an alternative tool (e.g. create_support_ticket or prepare_listing_claim) for cases that don't fit, so no explicit when-not guidance.

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

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

Beyond the annotations, the description discloses that the sign-in is revoked immediately, every issued token stops working, and the assistant-side stored token cannot be erased so the member must remove the connector manually. This is exactly the kind of operational consequence and limitation an agent needs, and it is consistent with destructiveHint=true and idempotentHint=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?

The description is four tight sentences, front-loaded with the core action, then consequences, then usage condition, then a necessary caveat. No sentence is wasted.

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

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

For a destructive, zero-parameter mutation with no output schema, the description supplies the action, immediate behavioral effects, invocation trigger, and a user-facing limitation. Nothing essential for correct invocation 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 there is no parameter semantics to explain. The baseline for a zero-parameter tool is 4, and the description adds no parameter information because none is needed.

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

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

The description uses a precise verb and resource: 'Disconnect this assistant from the member's FirmLedger account.' It is clearly distinct from the read-only connection_status sibling and leaves no ambiguity about what the tool does.

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

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

It explicitly states when to call it: 'when the member asks to remove, sign out or disconnect their account.' However, it does not state when not to call it or name an alternative sibling tool, which keeps it just below the top score.

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 a safe, read-only, idempotent operation, so the bar is lower. The description adds useful behavior beyond annotations: it returns a short list of specific fields plus an accurate total, and it restricts results to approved records. It does not cover rate limits or auth needs, but those are not central to this read tool.

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

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

Three concise sentences with the purpose front-loaded, followed by return shape and a field clarification. No sentence is wasted, though the final city/country sentence is somewhat redundant with the schema and could be folded into the first sentence.

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

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

For an eight-parameter search tool with no output schema, the description does important work by summarizing return fields and mentioning the accurate total. It omits details on type, limit/offset, and pagination, but those are fully covered in the schema. The definition is nearly complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters well. The description restates the searchable fields and gives city/country examples, but much of that duplicates the schema's own descriptions; it adds little additional parameter meaning. Baseline 3 is appropriate when the schema already does the heavy lifting.

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

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

States a specific verb (search) and resource (approved FirmLedger company records), lists the searchable facets, and explicitly distinguishes the tool from get_listing as the follow-up call. An agent can tell what this tool does and when it is the right first step without opening the schema.

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

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

Gives clear context: use this for picking a company before calling get_listing, and use city vs country for place terms. It names the alternative tool but does not state explicit when-not conditions, so it falls just short of the top score.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety is covered structurally. The description adds the meaningful non-annotation fact that user confirmation is required, which shapes how the agent must sequence 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?

Two short sentences, front-loaded with the operation and its allowed values, then the confirmation constraint. No filler and nothing wasted.

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

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

For a destructive, non-read-only mutation with no output schema, the confirmation requirement is covered, but the description omits side effects (e.g. notifications to the lead), reversibility, and what a successful status change implies. Adequate but with clear 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 only 33%, but the enumeration of statuses in the description merely repeats the schema's enum rather than adding format or constraint detail. The confirmation_token workflow is documented in the schema, not the description, so the description neither compensates for the gap nor adds much beyond what is already structured.

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

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

States a specific verb ('Move') and resource ('a lead in the user's business inbox') plus the full set of target states, so the agent knows exactly what operation this performs. It is distinguishable from read-side siblings like get_lead and list_leads by implication, but names no 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?

The description gives one usage constraint ('Requires the user's confirmation'), which is useful, but says nothing about when to choose this over alternatives such as reply_to_lead or when a status change is inappropriate. 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?

With annotations already declaring readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, the description adds real value beyond them: sender identity is auto-filled, the recipient's business email stays private, the owner is notified in their inbox, and a confirmation is mandatory. It could still say more about delivery/rate behavior, so a 4 rather than 5.

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

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

Two tight sentences: the first front-loads purpose and recipient scope, the second bundles the key behavioral constraints (auto identity, privacy, notification, confirmation). No filler.

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

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

For a 6-parameter mutation tool with no output schema, the description covers the critical flow (confirmation gating, privacy, notification) and the recipient scope. The token mechanics and return shape are left to the schema, which is acceptable, but a bit more on what a successful start produces would round it out.

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

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

Schema coverage is 67%, and the description adds only the note that the signed-in member email is used automatically (explaining why no email parameter exists). It says nothing about the message, phone, or looking_for parameters and does not compensate for the two undocumented schema fields. 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 names a specific verb and resource: 'Start a new FirmLedger Leads conversation with another approved, claimed business.' This is clearly distinguishable from siblings like reply_to_lead (continuing an existing thread) and list_leads/get_lead (reads), 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?

It states a concrete precondition ('another approved, claimed business') and a workflow requirement ('Requires the user's confirmation of the exact inquiry'), which tells the agent not to fire blindly. It stops short of explicitly naming alternatives or listing when-not-to-use cases, so it falls below the 5-level.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive. The description adds two traits the annotations cannot convey: edits can trigger a re-moderation rule when the core record changes, and the mutation is gated behind explicit user confirmation. It does not say how to clear a field or what the confirmation summary contains, 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?

The change operation and its scope are front-loaded in the first clause, with the confirmation requirement as a short second sentence. The parenthetical field list is dense but functional; nothing reads as filler.

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

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

For a 17-parameter mutation with no output schema, it covers the confirmation gate, re-moderation consequence, and editable surface. It leaves partial-update semantics (what happens to omitted fields) and failure modes unspecified, which is the main remaining gap.

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

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

Schema coverage is only 18%, so the description must carry more weight. It lists the editable field names, which confirms the editable set but largely restates schema property keys with no format, requiredness, or clearing semantics beyond what the schema already documents for listing, socials, and confirmation_token.

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

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

States a specific verb (change fields) and resource (a listing the user owns), then enumerates the editable fields and equates the tool with the dashboard edit form and PUT /api/v1/my/listings/:id. This clearly separates it from read siblings like get_my_listings and from the prepare_* siblings.

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

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

Gives the precondition that the user must own the listing and explicitly says confirmation is required, with the token flow described in the schema. It stops short of naming alternatives (e.g., prepare_listing_submission vs. this tool) or stating when-not to use it, so it is clear context rather than full routing guidance.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds two useful facts not in them: an 'approved company' prerequisite and that user confirmation is required. The detailed two-step token flow is left to the schema, so it is not quite exhaustive.

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

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

Two tightly written sentences with the action and its purpose front-loaded; no filler or repetition.

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

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

For a two-parameter mutation tool with no output schema, the description plus the fully documented schema and annotations give an agent enough to call it correctly. The confirmation handshake is explained in the schema rather than the description, which is acceptable but leaves a small gap at the description level.

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

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

Schema description coverage is 100%, so the schema already documents both parameters including the confirmation_token flow. The description only echoes the 'approved company' constraint on listing, adding little beyond the schema — baseline 3 applies.

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

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

States a specific verb (add), resource (company to the user's watchlist) and the benefit (notified when its record changes). An agent can immediately distinguish it from watchlist_remove or get_watchlist without opening any schema.

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

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

Implies the usage context clearly (add to be notified of record changes) and flags the confirmation prerequisite, but never names alternatives such as watchlist_remove/get_watchlist or states when NOT to use it.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the mutation/safety profile is covered. The description adds the confirmation gating step, but the mechanics of that flow (action_summary + token, second call with same args) live entirely in the schema's confirmation_token description, so the prose adds little beyond what structured fields give.

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

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

Two sentences, zero padding, with the action and its precondition front-loaded. Every sentence earns its place.

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

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

For a two-parameter destructive tool with full schema coverage and clear annotations, the description plus structured fields cover what an agent needs: what it does, that it mutates the watchlist, and that confirmation is required. The reversible/irreversible consequence of removal is left implicit, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100% — the 'listing' identifier formats (slug, name, FL ID, profile URL) and the two-step 'confirmation_token' protocol are fully documented in the schema. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Remove a company from the user's watchlist'), which is unambiguous on its own. It does not explicitly differentiate against the obvious sibling watchlist_add or the related request_listing_removal, but the purpose is crystal clear.

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

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

It specifies that the action 'Requires the user's confirmation', which is a genuine usage precondition, but gives no guidance on when to reach for this tool versus siblings like watchlist_add or request_listing_removal, nor any exclusions. 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.