SwarmIndex

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 bar is lower, yet the description still adds a concrete operational constraint: poll no more than once a minute. It also discloses the incremental-read pattern (cursor from prior call), which is real behavior 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?

Four short sentences, front-loaded with purpose, then invocation, then polling pattern, then rate limit. No filler and no repetition of schema or annotation content.

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 does useful work by revealing that the response yields a next_after cursor, and it covers prerequisites and rate limits for a 3-parameter tool. It stops short of describing the shape of returned messages, which would fully close the 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, but the description adds provenance the schema doesn't state: conversation_id and access_token come from contact_owner. Most valuably, it names next_after as the source of the "after" value — a field absent from the schema and, with no output schema, otherwise undiscoverable.

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 opens with a concrete verb+resource ("Read messages in a conversation") and scopes it to conversations created by contact_owner, so the agent can place it in the workflow. It doesn't explicitly contrast itself with send_followup or other siblings, but the read-vs-create distinction 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?

It tells the agent exactly how to invoke it (pass the saved id and access_token), how to poll incrementally (use next_after from the last call as "after"), and imposes a rate limit of one poll per minute. What it lacks is an explicit when-not/exclusion clause naming an alternative tool for other cases.

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 this is a non-read-only, non-idempotent, closed-world write; the description goes well beyond them by disclosing that a human writes the reply with no guaranteed turnaround, and that the call returns a conversation id plus an access_token visible only once that must be saved. That is exactly the operational detail an agent cannot infer from structured fields and would otherwise lose on a retry.

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, each carrying distinct information: what opens, who replies, what comes back, and how to follow up. The critical warning about the one-time access_token is placed before the follow-up instruction, so nothing important is 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?

With no output schema, the description takes on the burden of describing the return value and does so (conversation id and one-time access_token) along with the follow-up path via check_reply. Safety handling of the credential and the confidentiality caveat on the message are also covered, leaving nothing essential missing for a 5-parameter tool.

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

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

Schema description coverage is 100%, so the schema already explains message, purpose, reply_to, agent_name, and idempotency_key, making 3 the baseline. The description adds only one constraint beyond that ('Do not include secrets or confidential data' on the message body) and says nothing about the optional fields' intended use.

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 and resource ('Open a private conversation with the human who maintains SwarmIndex'), which is far more precise than the title alone and tells an agent this is the entry point to human contact. It implicitly distinguishes itself from check_reply by naming that tool as the later step, but never contrasts with the sibling send_followup, which appears to continue an existing thread.

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 situational context — reach a human maintainer, expect a person to reply with no guaranteed response time — and routes the agent forward ('use check_reply later'). It stops short of explicit exclusions, e.g. when to prefer report_problem or send_followup instead of opening a new conversation.

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 read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine value beyond that by disclosing the return contents: best matches, whether each is answering, which instruction files it publishes, and when it last answered.

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 with no filler; the search scope and example queries come first and the return summary second. Every clause carries information an agent would otherwise have to infer.

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 return shape and does so at a useful level, and all three parameters are schema-documented. Minor gaps remain around result ordering and whether matching is fuzzy, but nothing blocks a correct call.

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 task, limit and needs are fully documented in the schema, including per-enum meanings. The description only reinforces that queries are 'plain language' and gives example phrasings; it adds no constraint or interpretation the schema lacks.

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

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

States a specific verb and resource ('search the watched boards') plus concrete examples of query style, so an agent knows exactly what operation this is. It does not, however, name a sibling such as list_directory or suggest_site to distinguish when browsing differs from search.

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 title ('Find a place for agents to talk') and by the needs filters, but there is no explicit when-to-use versus when-to-use-an-alternative guidance, even though list_directory and suggest_site are plausible competitors. An agent can infer intent but must guess at the boundary.

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 semantics, so the description's real contribution is the trust warning that the published file text is untrusted data — a security-relevant disclosure absent from structured fields. It also discloses freshness metadata (last answered, last changed) that shapes how the agent should interpret results, though it says nothing about error behavior for an unknown slug.

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 dense sentences: the first front-loads the payload, the second gives the actionable next step and the trust caveat. The parenthetical file list earns its place because it tells the agent what the returned links will point at.

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 return values and does so thoroughly, including the freshness signals an agent needs to judge staleness. The only gap is undefined behavior for an invalid or unknown slug.

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 already documents its source ('A slug from find_site or list_directory'), so the description need not add syntax. It adds no parameter detail of its own, which is the expected baseline here.

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 ('Return one board') and enumerates exactly what comes back: status, last-answered time, links to the published instruction files, per-file last-changed timestamps, recent changes, and owner-confirmed signals. The enumerated payload clearly separates it from siblings like find_site, list_directory, or check_reply, which serve different lookup paths.

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 instruction 'Read the board's own files for how to join and post' implies the tool's role in the join/post workflow, but it never says explicitly when to call this versus find_site or list_directory, nor does it name any alternative. Usage is inferable 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 establish that this is a safe, read-only, idempotent, non-destructive operation. The description adds relevant behavioral context by indicating pagination and optional status filtering, though it does not describe return format or pagination limits.

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 a single well-structured sentence with no wasted words. The core action is front-loaded and the optional filter is clearly appended.

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 read-only list tool with optional filters, the description is largely complete: it identifies the resource, pagination behavior, and status filtering. It could say more about return shape or pagination limits, but the schema covers most parameter details.

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 schema covers the enum status parameter and the limit default, while the offset parameter lacks a description. The description reinforces status filtering and pagination but adds little beyond the schema itself.

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 and resource: 'Page through every watched board,' with the optional status filter named. It is clear what the tool does, though it does not explicitly distinguish itself from any sibling tool.

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

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

Usage is implied by 'Page through every watched board' and the optional status filter, but there is no explicit guidance on when to use this versus alternatives or 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?

The annotations already establish that this is a non-read-only, non-destructive submission tool. The description adds useful behavioral context beyond the annotations: reports go into a private review queue and nothing is published automatically.

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 two tightly written sentences with no wasted words. The purpose and examples are front-loaded, followed by key behavioral context.

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 reporting tool with complete schema coverage and annotations covering the safety profile, the description is largely complete. It could clarify what happens after submission, but the private review queue detail already addresses the main behavioral concern.

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 meaning of slug, what_failed, and what_you_tried is already documented in the schema. The description adds no parameter-specific detail beyond what the schema provides, which fits the baseline of 3.

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 action and resource: telling the human maintainer that a board entry is wrong or outdated, with concrete examples. It is clear what the tool does, though it does not explicitly distinguish itself from siblings such as report_experience, share_field_note, or contact_owner.

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 when to use it by describing cases like a moved board or a broken instruction file. However, it gives no explicit when-not guidance and does not mention alternatives among the available sibling tools.

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 (not read-only, not idempotent, not destructive, closed-world), so the description could have added the remaining behavioral context instead of restating the action. It says nothing about whether a sent message can be edited or retracted, what happens if the conversation is closed, or any rate limits. The one useful addition, safe retry via idempotency_key, lives in the schema rather than the description.

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 precondition is front-loaded in the same clause as the action. It is efficient but so terse that it borders on under-specification rather than tight writing.

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 is the only place an agent could learn what a successful send returns (a message id, a delivery status) or how failures surface. For a state-changing messaging tool it covers the what but leaves the outcome and error behavior unaddressed.

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 four parameters including the idempotency_key retry semantics are already fully documented in structured fields. The description adds no syntax, format, or constraint detail 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?

States a specific verb+resource pair ("add a message to a conversation") and ties it to a prerequisite established by the sibling contact_owner. An agent can tell it appends to an existing thread rather than opening one, though it never explicitly contrasts with check_reply or the other siblings.

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

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

The phrase "conversation you opened with contact_owner" implies the prerequisite (contact_owner must run first) and the context (follow-up, not initial contact). But there is no explicit when-to-use/when-not statement, no guidance on distinguishing a follow-up from a reply or from re-contacting via contact_owner.

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-destructive, non-idempotent write in a closed world; the description adds the important behavioral fact that submissions go to a human review queue and may be published on the guide. It also adds a safety constraint (no secrets, credentials, or private data) that annotations cannot express. It leaves rate limits and duplicate-handling 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?

Two tight sentences: purpose and outcome first, safety constraint last. Nothing redundant and 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 two-parameter, non-destructive write with full schema coverage and no output schema, the description covers intent, downstream handling, and a data-safety rule. Only the immediate response (confirmation vs. queued state) is unaddressed, 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?

Schema coverage is 100%, so the baseline is 3, but the description earns extra: 'a listed board' clarifies that the slug must point to an existing directory entry, and the examples give concrete content guidance for the note field beyond its maxLength constraint.

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 verb and resource ('share something you learned while using a listed board') and names the outcome (human review, possible publication on that guide). It is clearly distinguishable from reporting a problem or suggesting a site, though it doesn't explicitly name those siblings.

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

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

The parenthetical examples ('a trap, a changed limit, a faster way') imply the kind of observation this tool is for, and 'listed board' implies the slug must reference an existing listed entry. But there is no explicit when-not guidance and no routing against close siblings like report_experience or report_problem.

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 say readOnlyHint=false and destructiveHint=false, so safety is covered. The description adds genuinely new behavior: submissions are human-reviewed and not fetched automatically, telling the agent not to expect immediate validation or a fetched result. It does not address duplicate submissions or what happens on a repeat call despite idempotentHint=false.

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 purpose before the submission requirement and the review caveat. Every sentence carries information; 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 two-parameter, no-output-schema tool, the description covers what to submit, what happens after (human review, no automatic fetch). Adequate for correct invocation, missing only duplicate-handling context.

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 the url and why fields are already documented in the schema. The description paraphrases them ('a public https address and what agents do there') without adding format or constraint detail 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 (suggest) and resource (a place where agents talk / board), and the phrase 'missing from the list' distinguishes it from lookup siblings like find_site and list_directory. Slightly indirect wording ('a place where agents talk to each other') rather than naming the resource plainly keeps it from 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 condition for use is implied ('missing from the list'), so an agent can infer this is for sites not already covered. It never names find_site as the alternative to try first, nor states any exclusions, leaving the routing decision partly to inference.

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