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 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 the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds valuable context: the content is 'moderated' and 'accuracy-gated', it is scoped to one company, and it hints at the Pro tier, all of which go beyond the structured annotations.

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

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

A single front-loaded sentence that moves from the tier qualifier to the resource and the returned fields with no wasted words. It could name the alternative tool in the same breath, but it is well-sized and readable.

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

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

For a read-only, well-annotated, two-parameter tool, the description covers the essentials: what is fetched, for whom, and what fields come back, which compensates for the absent output schema. It stops short of stating ordering, recency window, or empty-result 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%, so both parameters are already well documented in the schema (limit 1-12, listing accepts slug/name/ID/URL). The description adds only the 'one company' scope and does not clarify the limit default or pagination, so it does not exceed the baseline established by 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+resource: recent moderated news headlines about one company, including the fields returned (dates, publishers, links). An agent can tell it fetches news rather than refreshes it, but the description never names refresh_listing_news as the mutation counterpart, so sibling differentiation is only 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?

Usage is implied by 'about one company' and 'the same accuracy-gated stories shown on the profile's news panel', which signals a read of already-moderated content. However, there is no explicit when-to-use or when-not guidance, and no mention of choosing this over refresh_listing_news or get_listing.

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, 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 carry readOnlyHint/idempotentHint/openWorldHint=false, so the safety profile is covered. The description still adds real behavior beyond them: unapproved listings are excluded from results, the Pro-tier gating, and the projected return fields. It omits pagination/result-size behavior despite limit and offset existing.

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

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

It is short and front-loaded, but the trailing clause 'keyword: title, company, location, posted date and where to apply' reads ambiguously — it is easy to parse the colon list as additional filter parameters rather than the fields returned. That structural ambiguity costs a point.

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 names the returned fields, which is genuinely helpful. However, for a paginated list tool with limit/offset, there is no guidance on result volume, defaults, or paging, leaving a noticeable 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 60% (limit and offset have no descriptions anywhere), and the description mentions only company, location, and keyword, which the schema already documents in more detail. It adds no format or syntax beyond the schema, so it lands at the baseline for partial coverage.

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

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

States a clear resource (open roles at approved FirmLedger companies) and the filtering axes, and the 'approved companies only' restriction meaningfully scopes it against siblings like search_listings or get_listing. It stops short of explicitly differentiating itself from those siblings in the text.

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

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

The description enumerates what can be filtered but never says when to choose this tool over search_listings or get_listing, nor any when-not condition. Usage is only implied by the word 'jobs'.

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 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 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: results are limited to approved records, a short list of specific fields is returned, and an accurate total is provided. It does not discuss pagination or rate limits beyond what the schema says.

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

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

Three sentences, front-loaded with purpose and filters, followed by return shape, then a focused usage note. The parenthetical return-field list is dense but earns its place because no output schema exists.

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 listing the returned fields and mentioning the accurate total. It also states the approved-records scope and the relationship to get_listing. Pagination details are left to the input schema rather than the description.

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

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

Schema description coverage is 100%, so the parameter baseline is 3. The description goes slightly beyond the schema by clarifying the city/country split with examples ("Nairobi" vs "Kenya") and by mapping query to name or keyword, though it does not mention type, limit, or offset.

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), resource (approved FirmLedger company records), and supported filters (name/keyword, category, country, city, verified status). It also distinguishes itself from the sibling get_listing by framing the search as the step before fetching a full listing.

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

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

Explicitly says the results are for picking the right company before calling get_listing, and gives a concrete usage rule for city versus country. It lacks explicit when-not-to-use guidance or mention of alternatives like list_categories/list_countries, though the schema partially covers category enumeration.

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?

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.