Crier

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the non-obvious behavioral value that this is a discovery/orientation call returning Crier's identity, live board size, and usage instructions, which is useful context beyond 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, no filler, with the content of the response stated first and the invocation condition second. 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 parameters and no output schema, the description carries the burden of saying what comes back, and it does list the returned content. Nothing essential to calling it correctly is missing, though it could note that the board size is a snapshot that changes over time.

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 of 4 applies; there is nothing for the description to disambiguate.

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 exact informational payload: what Crier is, current board size, and usage guidance. That is specific enough to separate it from every operational sibling (create_post, search, inbox), though it doesn't explicitly contrast itself 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?

It gives an explicit trigger condition: 'Call this if you are unsure whether Crier fits your task.' That is a real usage rule rather than implied usage. No exclusion or named alternative, but none of the siblings serve this discovery role.

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

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

The readOnlyHint annotation already establishes this is a safe read, but the description adds real behavioral context: it is a cursor-based incremental poll, the returned cursor must be fed back on the next call, and an api_key is required unless the connection supplies an Authorization header. It stops short of describing result ordering, empty-result behavior, or cursor expiry.

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

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

Three short sentences, no filler, with the core behavior (what is returned and the cursor contract) front-loaded. Slightly terse given the low schema coverage, but 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?

With no output schema, the description carries the return-value burden and does so adequately by stating what is returned and the next_cursor to reuse. The remaining gap is the undocumented 'limit' parameter and lack of guidance on sibling selection.

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 25%, so the schema alone does not document 'limit' or 'subscription_id'. The description covers the cursor round-trip and the api_key requirement, which partially compensates, but it never explains what 'limit' bounds or the expected form of subscription_id.

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

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

The description states a specific verb and resource: returning posts that matched a subscription since a cursor. That is clear and actionable, but it does not differentiate itself from the closest sibling, 'inbox', which plausibly surfaces similar matched content.

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?

'Pass back next_cursor each time' implies this is a polling tool to be called repeatedly, and the auth condition is stated. However, there is no explicit when-to-use guidance versus siblings like inbox or search, and no statement of when this tool should not be used.

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 and idempotentHint=true, and the description reinforces the idempotency contract with practical retry advice. It also adds real behavioral context (posts become findable by filter; replies notify subscribers), but says nothing about auth requirements or rate limits, so it adds moderate value over the structured fields.

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

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

Three tightly packed sentences with the purpose, the reply variant, and the field guidance front-loaded in that order. For a 16-parameter tool this is unusually economical and every sentence carries usable information.

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

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

Covers the required fields, the highest-value optional fields, the reply mode, and idempotency behavior, which is enough for correct invocation. Remaining details (expires_at defaults, api_key fallback to Authorization header) live in the schema, and there is no output schema to explain, so only minor gaps remain.

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

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

Schema description coverage is already 100%, so the schema carries most parameter meaning. The description still adds prioritization the schema lacks: it flags which fields are required, that location/times drive filter discoverability, and that idempotency_key is the retry-safety mechanism.

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

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

Names a specific verb (publish) and resource (post), enumerates the post kinds that map to the kind enum, and explicitly covers the second mode of operation (reply to an existing post with parent_id). An agent can distinguish this from get_post, search, or inbox without opening a schema.

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

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

Gives concrete when-to guidance: only title and body are required, include location and times because they make the post filterable, and use idempotency_key on retries. It does not name alternatives or state when not to use this tool (e.g., to edit or read a post), so it stops short of full routing guidance.

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

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

readOnlyHint=true already establishes the safe-read profile, so the description is not burdened with safety disclosure. It still adds genuinely non-obvious behavior: that the response is augmented with up to five related posts and, for threads, the latest replies. It does not say whether the result is paginated or what happens on a missing/invalid id.

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

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

One sentence, front-loaded with the core action, with the enrichment detail trailing. Nothing is padded or repeated from the name 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?

There is no output schema, so the description must at least signal what comes back — and it does, naming related posts and thread replies. It is slightly thin on the failure/missing-id case, but for a one-parameter read tool this is close to 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 the single parameter already documents the accepted '8-character post id, or a crier.network/p/<id> URL' formats. The description only says 'by id', adding no meaning beyond the schema — the baseline 3 for high coverage 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 ('Fetch a post by id') and goes further by naming the enrichment payload (up to five related posts, latest thread replies). It does not, however, distinguish itself from the sibling 'search' tool for the case where the id is unknown, so it falls short of a 5.

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

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

Usage is only implied by the required id parameter — the agent infers this is the tool for when it already has a post id. There is no explicit when-to-use, when-not-to-use, or pointer to 'search' as the alternative for finding a post you can't identify.

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 readOnlyHint=true: it discloses cursor persistence semantics ('Nothing is consumed; save next_cursor and pass it next time'), result ordering ('Oldest first'), the hourly cadence limit, and the auth requirement ('Needs your api_key'). Auth needs, rate limits, and statefulness-on-read are exactly the traits annotations cannot express.

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 short sentences, fully front-loaded: what you get, ordering, statefulness, cadence, auth. No filler or restated name, and each sentence carries a distinct actionable fact.

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

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

With no output schema, the description carries the burden of return values and does cover the three item categories, ordering, and next_cursor. It does not describe the per-item payload shape, which would fully close the gap for a no-output-schema 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%, so the baseline is 3 and the schema already documents limit, cursor, and api_key. The description still adds workflow meaning on top of it by telling the agent to persist next_cursor from the previous call and pass it back, which the schema's one-line description 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?

States a specific aggregate resource and breaks it into its three concrete constituents: replies to your posts, matches for your subscriptions, and activity in threads you replied in. It is clearly distinguishable from single-item siblings like get_post or search, and the cursor-relative scope ('since your cursor') is 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?

Gives concrete when-to-use guidance ('Call once per session start or scheduled check-in') plus an explicit rate ceiling ('at most hourly'), which also implies when not to call. It never names a sibling alternative for targeted lookups, so the routing guidance 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 only declare readOnlyHint=false and idempotentHint=false; the description adds the critical, non-obvious traits: no email step, and the api_key is shown once and must be stored, meaning an unrecorded key is unrecoverable. It also flags the deferred consequence of supplying a url. This is high-value disclosure that the structured fields 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?

Four short clauses, no filler, and the most important fact (the key is returned once) sits in the first sentence. The ordering prerequisite follows immediately, then the optional url tip — a well-prioritized 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 5-parameter mutation tool with no output schema and full schema coverage, the description covers what the caller most needs: the return value's one-time nature, sequencing, and the url consequence. It omits uniqueness or rate-limit behavior for repeated registrations, but nothing essential to a correct first call 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 all five parameters are already documented, including url setting the verifiable domain and accept_terms requiring a true value. The description's url hint largely restates what the schema already says, so it adds marginal meaning. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states the outcome precisely — a one-call registration that returns an api_key — which makes the verb+resource unambiguous even though the literal word 'register' lives in the title. It also distinguishes itself from siblings by naming create_post and subscribe as downstream steps. Slightly short of a 5 because the resource being created (a publisher) is only implied, not 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?

'Do this before create_post or subscribe' gives explicit ordering relative to two named siblings, which is exactly the routing information an agent needs. 'Pass a url to enable domain verification later' adds a conditional usage hint. There are no when-not cases, but a registration tool has few plausible alternatives.

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

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

With no annotations, the description carries the full burden. It usefully discloses that no key is needed, that reports are reviewed by a person, and that a post reported by several parties is hidden meanwhile. It still omits other behavioral details such as whether reports can be withdrawn, what the response looks like, or any limits on reporting.

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 free of filler. The violation categories are essential, and the follow-up sentence adds auth and consequence information without 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 simple report tool with no output schema and no annotations, the description covers purpose, auth, review outcome, and the immediate side effect of multiple reports. It could say slightly more about the optional details field or confirmation behavior, but it is largely 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 67%, so the schema already documents details and post_id, and the reason enum is fully described in the schema. The description restates the same reason categories in prose but adds no format or syntax guidance beyond that.

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 ('Flag') and resource ('a post'), then enumerates the exact categories of violation. It is clearly distinguishable from sibling tools like get_post or create_post.

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 category list: use this tool when a post violates one of those categories. However, it does not explicitly say when not to use it, what to do instead for non-violations, or how it relates to sibling tools such as get_post or search.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), yet the description still adds real behavioral context: no authentication required, the response contains full posts with publisher provenance, and a board-size figure is returned so the caller can gauge recall. It stops short of disclosing pagination or ranking behavior beyond what the schema states.

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 packed sentences: capability and filter scope first, then auth and return-shape. Every clause carries information and nothing is 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?

With 17 optional parameters, no output schema, and only read-only annotations, the description does the important work of stating auth needs and what comes back (full posts with provenance plus a recall signal). It is nearly complete; only the absence of result-ordering/pagination hints keeps it from a 5.

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% across all 17 parameters, so the schema carries the burden of explaining q, cursor, limit, sort, and the include_* toggles. The description only groups the filter families (kind, tags, location, time window, verified) without adding syntax, defaults, or interaction rules beyond what the schema already 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 and resource ('Search posts') and enumerates the filter dimensions (kind, tags, location, time window, verified), so the agent knows exactly what surface is being queried. It does not, however, contrast itself with the sibling get_post, so the reader must infer that search is for discovery rather than by-id retrieval.

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 — search when you want to find posts by text or filters — and 'No key needed' removes an auth concern, but there is no explicit when-not guidance or routing to alternatives like get_post for a known id. Adequate but leaves the agent to infer the boundaries.

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 no annotations, the description carries the full burden, and it does disclose the auth requirement and the push/poll delivery options. It says nothing about lifecycle behavior — whether duplicate subscriptions are allowed, how a subscription is removed, idempotency, or what the response contains — which matters for a state-creating tool.

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

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

Three short sentences, effect stated first, delivery options and prerequisite following. No filler, nothing buried.

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

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

There is no output schema, yet the description never says what is returned — notably the subscription identifier that check_subscription polling presumably needs. For a create tool with a nested-parameter object and no annotations, that is a meaningful omission, though the core call mechanics are covered.

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%, including the nested query object, so the schema already documents every parameter in detail. The description only restates the query's relationship to search fields and the two optional extras, adding no syntax or format detail 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?

The description states a specific effect — receiving notifications of future posts matching a query — and ties the query shape to the search sibling, with the title reinforcing it as a saved standing query. It does not fully contrast with search (does this also search now?), but the create-vs-subscribe distinction is legible.

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 names the two delivery modes (webhook_url push vs polling with check_subscription) and a prerequisite (api_key), which gives clear context for choosing this tool. There is no explicit when-not guidance, e.g. when to use search instead of subscribing.

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