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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond them: that the downstream write is rate-limited and that this check exists to avoid a 409, which tells the agent why the read is cheap.

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

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

A single sentence that front-loads the action and its outcome, then appends the motivating rationale. 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, and the description only loosely implies the return shape ('whether a tool is already listed or awaiting review'). It could say what the response conveys when both url and name are provided, but for a 2-param read tool with full annotation coverage it is largely sufficient.

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

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

Schema description coverage is 100% and both url/name are documented in the schema, so baseline is 3. The description adds no additional semantics about how url and name interact or whether either alone suffices, despite both being optional.

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 (check) and resource (tool already listed or awaiting review), and pins it to the endpoint GET /api/agent/check. An agent can immediately distinguish it from submit_tool or get_submission.

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: call this 'before submitting' to avoid a rate-limited write returning 409. It names the sibling action (submitting) and the failure it prevents, though it doesn't explicitly say when not to use it or name submit_tool by name.

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

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

Annotations only say readOnlyHint=false and openWorldHint=true; the description adds genuinely useful behavior: the token is persisted locally (a side effect on the client), it is bound to the account, and subsequent submissions are owned by that account. It stops short of describing failure modes (invalid/expired code) or whether an existing stored token is overwritten.

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

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

Two tight sentences: the core action and its local-storage effect come first, the endpoint is parenthetically appended, and the ownership consequence follows. No filler, everything front-loaded.

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

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

With no output schema and only sparse annotations, the description does cover the essential outcome (a stored account-bound token) and the mechanism (POST endpoint). Minor gaps remain around error handling and token replacement behavior, but nothing critical for invoking it correctly is missing.

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

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

Schema coverage is 67% (code and name are described, email is not), so the schema already does most of the work. The description ties 'email login code' to the email/code inputs but adds no format, constraint, or meaning beyond what the schema states. Baseline 3 is appropriate.

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

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

States a precise verb+resource ('Exchange an email login code for an account API token and store it locally') and pins the concrete endpoint POST /api/agent/token. Combined with the sibling start_login, an agent can immediately see this is the second half of a login flow rather than a standalone operation.

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

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

The description implies the flow (an email code must exist, presumably from start_login) but never states when to call this versus alternatives, nor any prerequisites or failure conditions. Usage is inferable from the name and the phrase 'email login code', but nothing is explicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by enumerating the concrete status values and the fields surfaced (link tier, paid checkout verified), and by exposing the underlying endpoint shape. It doesn't discuss rate limits for polling or error/auth behavior.

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

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

One sentence, front-loaded with the action and payoff, with the endpoint parenthetical as compact supporting context. No filler or repetition of the tool name.

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

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

With no output schema, the description carries the burden of describing returns and does so by listing the status enum and the two additional result fields. For a single-parameter read tool this is nearly complete; minor omissions are polling cadence and what happens for an unknown id.

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 id parameter is already documented with its provenance ("submission_id returned by submit_tool"). The description adds nothing further about the id's format or constraints, 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 (poll/get status) plus the resource (a submission) and enumerates what it reports: status pending/approved/rejected, link tier, and paid-checkout verification. An agent can tell it apart from siblings like submit_tool or list_categories. It doesn't explicitly name an alternative sibling the way a 5 would, but the operation 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?

"Poll a submission's status" implies the usage context of repeatedly checking an asynchronous submission after submit_tool, which is real guidance. However, it never states when to use this versus other lookups, no prerequisites, and no stopping condition for polling. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral value by disclosing where the values are consumed (submit_tool) and how mismatches are handled (categorySuggestions), which is not derivable from the annotations or the empty 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 compact sentences, front-loaded with the purpose and followed by the downstream usage instruction. Every clause carries information; nothing is padding.

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

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

With no output schema, the description carries the burden of describing returns, and it does so ('valid category slugs'). Combined with the empty input schema and the usage routing, an agent has enough to call it correctly. It omits nothing critical, though a note on response shape or ordering would make it airtight.

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 disambiguate; baseline is 4. The description correctly implies a no-argument call by not describing any inputs.

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

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

States a specific verb (list) and resource (valid category slugs), and even cites the underlying endpoint GET /api/agent/categories. It names the sibling tool (submit_tool) that consumes the output, so an agent can distinguish it from the auth and submission tools 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 routes usage: feed the slugs into submit_tool, and put anything that doesn't match into categorySuggestions. That is clear when-and-how guidance. It stops short of stating the ordering constraint (call this before submit_tool) or what to do if the list is empty.

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 mark this as a non-read-only, open-world operation; the description corroborates by disclosing the concrete side effect (an email is sent) and the two-step handshake with the inbox. It adds real context beyond the annotations but omits rate limits, code expiry, and failure behavior.

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

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

Two sentences, zero filler, and the action is front-loaded before the endpoint and the next-step instruction. 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 one parameter, full schema coverage, no output schema, and annotations covering the safety profile, the description supplies everything needed to invoke it and continue the flow. Missing only minor operational detail such as code validity window or error cases.

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 'email' property already has a descriptive string, so the schema carries the semantics. The description adds only implicit meaning (the email receives the code) and no format or constraint detail beyond what the schema states; 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 ('Email a one-time login code') plus the underlying endpoint (POST /api/auth/request-code), and the 'browserless onboarding' framing distinct from the sibling complete_login. An agent can tell exactly what this does and where it sits in the flow without opening the schema.

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

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

Explicitly names the follow-on sibling ('call complete_login') and the intermediate step (read the code from the inbox), so the when-to-use path is clear. It lacks any when-not guidance (e.g., already authenticated, code still valid), so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true. The description adds genuinely new behavior beyond those: the listing is queued as pending, an editor must review it, it is never published automatically, and unknown categories are merely recorded for the reviewer. It still omits what the submission returns (e.g. an id or status) for a mutating call.

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

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

Three tight sentences, front-loaded with purpose and endpoint, then review behavior, then category/auth prerequisites. No filler and nothing repeated from the schema.

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

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

Covers the key non-obvious facts for a 16-parameter mutating tool with no output schema: pending review, auth prerequisite, optional categories. It does not describe the shape of the response or mention duplicate-checking, which an agent would need to call this well.

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

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

Schema description coverage is 100%, so the schema already documents all 16 parameters including the resubmit idempotency nuance and the proof/verificationUrl pairing. The description only restates that categories are optional and unknown ones are recorded, adding little beyond the schema.

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

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

States a specific verb (submit) and resource (a tool listing to the Altimateguide directory) plus the concrete endpoint POST /api/agent/submit. The 'for editorial review' qualifier distinguishes it from upgrade_listing, the paid 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?

Gives clear context: submissions are queued as pending and never auto-published, categories are optional, and a token is required via complete_login or ALTIMATEGUIDE_AGENT_TOKEN. It does not, however, route the agent away from this tool when a duplicate exists (check_duplicate) or explicitly name upgrade_listing as the paid alternative in the description text itself.

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

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

Annotations only declare the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false); the description adds substantive behavior beyond that: the `paid` path returns a Dodo checkout URL carrying the submission id, payment is verified server-side by a webhook, and the tool does not publish or self-grant dofollow status. These are real operational facts an agent needs, not restatements of 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 tight sentences, front-loaded with the action and enumerations, then the paid-path mechanics, then the single important exclusion. Every sentence carries information, though the internal jargon (Dodo webhook, dofollow) assumes domain familiarity.

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

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

With no output schema and full schema coverage, the description responsibly discloses the return of the `paid` path (a checkout URL) and the external verification flow. It leaves the response shape for the sayabout/badge paths unspecified and does not state that an existing upgrade request may be reused, but the essentials for correct invocation are present.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already explains path, slug, submissionId, and verificationUrl. The description mostly echoes the schema (paid returns a Dodo URL, sayabout/badge need a Wall of Love URL) rather than adding new syntax or constraint details, so it neither elevates nor diminishes parameter understanding.

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

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

The description names a specific verb and resource ('Choose how a listing you own earns a dofollow link') and enumerates the three concrete paths (sayabout, badge, paid) that define the operation. The closing sentence 'Nothing publishes or self-grants dofollow here' distinguishes it from publish-oriented siblings like submit_tool without the agent needing to open any schema.

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

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

It clearly states the context of use (a listing you own, choosing an earning path) and identifies when the `paid` variant applies versus the verification-based variants. It stops short of naming sibling tools as alternatives or stating explicit when-not-to-use conditions, so it is clear context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it distinguishes a missing token from a revoked/expired one, telling the agent what failure modes to expect.

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

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

Two compact sentences with zero filler. The core action and its diagnostic value are front-loaded, with the endpoint reference tucked at the end where it costs nothing.

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

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

For a parameterless read tool with no output schema, the description covers what the agent needs: what it confirms and what it reports. It stops short of describing the returned account fields or the error payload shape, which is a minor gap given the simplicity.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing about parameter meaning needs to be conveyed, and the description correctly implies the token comes from configuration rather than an argument.

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 (confirm token liveness, report owning account) and even names the underlying endpoint. It is clearly distinguishable from the login/session siblings, which deal with acquiring credentials rather than validating 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?

Gives clear context for when to reach for it: verifying a configured token is live and diagnosing whether a failure is a missing token versus a revoked/expired one. It does not name an alternative tool, but no sibling plausibly overlaps with this diagnostic role.

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