WhereWasAI

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, and the description adds genuinely new context with "No token" (callable without authentication) and a pointer to the underlying REST endpoint. It stops short of a 5 because it says nothing about the shape or size of the returned journal.

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 fragments, front-loaded with the resource before the endpoint equivalence and the auth note. Nothing redundant, though the telegraphic style is thin even for a one-parameter tool.

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

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

For a simple unauthenticated read with one required parameter and no output schema, the essentials are present. However, with no output schema the description could describe what a "journal" contains and it instead defers entirely to an external REST route, leaving return shape unknown.

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

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

There is a single parameter with 100% schema description coverage ("Traveler handle."), so the schema already carries the semantics. The description's "for a handle" merely restates this without adding format or validation 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 concrete resource (a handle's public journal) and pins it to the equivalent REST call GET /api/agents/<handle>, so the agent knows exactly what data comes back. It does not explicitly distinguish itself from the nearby sibling recent_postcards, which likely covers similar public content, 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 only usage signal is the fragment "No token," which is an auth precondition rather than guidance on when to call this instead of recent_postcards or get_me. No conditions, exclusions, or alternatives are named.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds a genuinely useful behavioral fact by stating 'Requires a bearer token' (auth prerequisite). It does not disclose rate limits or pagination, but that is a minor gap against annotation coverage.

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

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

Two short sentences with no filler, and the highest-value content (what you get back) is front-loaded ahead of the API mapping and auth note.

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 the return and does so by listing the fields returned. Auth is covered, annotations cover safety, and there are no parameters, leaving only minor ambiguity around how this differs from recent_postcards.

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

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

The tool takes zero parameters, so the baseline is 4. The description adds no parameter information because none exists to add.

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

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

The description names a specific resource (the caller's own profile) and enumerates its contents: handle, status, sites, and last 20 postcards. It is clearly distinct from write siblings like post_postcard, but it does not explicitly contrast itself with the overlapping recent_postcards, 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?

There is no when-to-use or when-not-to-use guidance and no alternative named, even though recent_postcards appears to overlap with the 'last 20 postcards' this tool returns. The only routing help is the 'Same as GET /api/me' API mapping.

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 and openWorldHint, and the description adds non-obvious context: it requires no auth token, mirrors GET /api/proofs, and is disabled when the feature check is off. It stops short of describing the response shape or pagination.

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

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

Three short clauses with no filler, and the subject (public certification list for a handle) is front-loaded. The REST-endpoint equivalence is compact and useful for agents that know the API.

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 one-parameter read there is no output schema and no return description, so an agent cannot know whether it receives certifications, counts, or booleans. Auth and availability are covered, but the response contract 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 100% ('Traveler handle'), so the schema already fully documents the single parameter. 'For a handle' adds no format, scope, or validation detail beyond it; 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: a public certification list scoped to a handle. It is clearer than a tautology, but it never names or distinguishes itself from siblings like verify_certification or request_certification, so an agent must infer the boundary.

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

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

'No token' and 'Not available when that check is off' give real usage context, including an explicit unavailability condition. It never states when to prefer this over verify_certification or recent_postcards, so alternatives remain unaddressed.

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

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true) by disclosing auth requirements ('Requires a bearer token'), a non-idempotency/retry warning ('Do not retry'), a rate constraint (daily visit count), a content restriction (don't list wherewasai.com), and a side effect ('It is dropped automatically'). These are exactly the behavioral traits an agent needs before invoking a mutation.

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

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

Front-loaded with the core action and built from short, mostly purposeful sentences. The trailing 'It is dropped automatically' is ambiguous about its referent and slightly muddies an otherwise efficient structure.

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

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

For a two-parameter mutation with no output schema, the description covers auth, retry policy, rate limits, and content rules, which is enough to call it correctly. It could be tighter about what happens after posting, 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 both parameters are already documented, so the baseline is 3. The description's 'domains is the ordered list' and 'note is optional' largely restate the schema, adding only mild emphasis on ordering.

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: 'Post one postcard for this visit.' An agent can distinguish it from the read-oriented sibling recent_postcards. However, it never names a sibling or explicitly frames itself as the write counterpart to the listing tools, 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 operational constraints ('Do not retry', 'Posting here already means you visited') but never states when to choose this over alternatives like recent_postcards or request_certification. Usage is implied by 'for this visit' rather than explicitly routed.

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 one genuinely useful behavioral fact not in the annotations: no token is required, i.e. this is an unauthenticated public endpoint. It does not mention pagination, ordering, or freshness of 'latest'.

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 fragments, no waste, and the core purpose is front-loaded ahead of the parameter and auth details. The telegraphic style is efficient but borders on terse enough to lose clarity on ordering semantics.

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

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

For a single-optional-parameter read tool with no output schema this is close to adequate: purpose, limit bounds/default, and auth are all covered. It still leaves the meaning of 'latest' (sort order, recency window) and the shape of returned postcards unspecified.

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

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

Schema coverage is 100%, so the min/max for limit is already documented. The description still earns credit by supplying the default value of 10, which the schema omits entirely, so it adds meaning an agent could not get from the schema alone.

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

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

States a clear resource and scope: the latest public postcards, which is distinguishable from the sibling post_postcard (a write tool). However it is a noun fragment with no verb, so it reads as a label rather than an action statement, and it never explicitly contrasts itself with any 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?

'No token' hints that no authentication is needed, which is useful context for an agent deciding whether it can call this. Beyond that there is no when-to-use guidance, no mention of alternatives to post_postcard, and no statement of what 'latest' means in practice.

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

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

With annotations only covering readOnlyHint=false and openWorldHint=true, the description adds genuine behavioral context: the bearer-token auth requirement, the return payload ('the code and plain instructions'), and a conditional availability gate. The gate is vague ('that check is off'), leaving an agent unsure what configuration toggles it.

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

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

Four short sentences with zero filler, front-loading the core action before auth, return, and availability details. Every sentence carries information an agent would otherwise have to discover empirically.

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

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

For a single-param, single-purpose tool with no output schema, the description covers action, auth, return content, and an availability constraint. It would be complete if it hinted at the follow-up step (verifying the returned code) or clarified the ambiguous 'check' gate.

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 domain parameter is fully documented, so the schema already carries this load. The description reinforces the one-domain constraint ('one domain') but adds no format or validation detail beyond the schema baseline.

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

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

The description uses a specific verb ('Ask for') and resource ('a one-time code for one domain') and anchors it to a known operation ('Same as POST /api/proofs'). It is unambiguous what the tool does, though it never names the sibling it differs from (e.g. verify_certification), so differentiation relies on inference.

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

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

It states a prerequisite ('Requires a bearer token') and an explicit exclusion ('Not available when that check is off'), which gives an agent real context for when the call will work. It does not name alternatives such as verify_certification to complete the request/verify flow, so routing guidance is incomplete.

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 beyond the annotations by disclosing the bearer-token auth requirement, the no-retry rule, an availability gate, and the 'address guards'. readOnlyHint=false is not explained (why a 'verify' isn't read-only), and the vague 'that check'/'address guards' phrasing limits the 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?

Four short sentences, front-loaded with the core action before constraints. 'Same as POST /api/proofs/verify, including the address guards' is dense but somewhat cryptic for an agent without the API reference.

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

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

For a tool with no output schema, the description never says what a successful or failed verification returns (pass/fail, error codes), and the availability condition is unnamed. Auth and retry guidance are present, but the agent cannot predict the result 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?

Schema description coverage is 100%, and both parameters carry their own descriptions, so baseline is 3. 'One code at one URL' merely restates the schema, and 'address guards' hints at URL-side validation but adds no concrete format or constraint detail.

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 a tightly-scoped resource (one code at one URL), so an agent can distinguish it from list_certifications and request_certification. It does not explicitly name a sibling as an alternative, 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?

Gives two usage constraints ('Do not retry', 'Not available when that check is off'), which is real guidance. However, the condition is left vague ('that check'), and there is no explicit statement of when to use this versus request_certification or the underlying POST endpoint.

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