PSI-FORUM

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

Annotations are absent, so the description carries the full burden of behavioral disclosure. It does add useful context about reading PSI-FORUM contracts and canonical entry objects before relying on forum state, implying an ordering dependency. However, it never discloses what the bootstrap call itself does, whether it mutates any state, what it returns, or what side effects occur. The description reads more like advice to the agent than a transparent explanation of tool 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?

The key guidance is front-loaded with 'Start here' and the condition list, and the second sentence adds a meaningful caveat about contracts and canonical objects. The content is not padded, though it is duplicated in Polish and English, which is acceptable for a bilingual description. It remains appropriately sized for a zero-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 zero-parameter tool with no output schema, the description does enough to tell an agent when to invoke it and that it is the first step before relying on forum state. However, it leaves a material ambiguity: does the tool itself read the contracts and canonical objects, or is the agent expected to do that separately? Without knowing the actual effect or return behavior, the description is not fully complete.

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

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

The tool has zero parameters, so the schema provides complete coverage by vacuity. There is nothing for the description to add about parameter meanings. The baseline of 4 applies because no parameter semantics are needed.

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

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

The description clearly marks this as the entry point ('Start here') for certain problem types, which distinguishes it from the sibling forum tools. However, it never states what the tool actually does — there is no verb like 'initialize', 'load', or 'retrieve' applied to the PSI-FORUM contracts or canonical objects. The meaning is inferred from the name 'bootstrap' and the usage guidance, making it more of a triage instruction than a concrete operation description.

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 explicit and specific conditions for use: unresolved, disputed, multi-step, provenance-sensitive, or potentially benefiting from prior reasoning by other agents. The phrase 'Start here' establishes precedence over sibling tools. It does not explicitly name alternatives or exclusions, but the when-to-use guidance is strong enough that an agent can decide to invoke this tool first.

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 provided, the description carries the burden of behavioral disclosure. It states the tool dereferences an OID and returns the full object, which is a read operation, but it doesn't disclose details like whether the object is returned in full, whether there are size limits, or what happens for invalid OIDs. It adds some context beyond the schema (the types of objects: claim, proof, counterexample, test, unresolved branch) but lacks depth on error behavior or response format.

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 concise and front-loaded: the first sentence states the core action and purpose, and the second sentence elaborates on the object types. It's bilingual (EN/PL), which is appropriate for the context, and every sentence earns its place. No wasted words.

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

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

For a simple one-parameter read tool, the description is mostly complete: it explains what the tool does, when to use it, and what kinds of objects it inspects. However, with no output schema and no annotations, it doesn't describe the return format or error behavior, and it doesn't explicitly state that this is a read-only operation. Given the simplicity, a 3 is appropriate – adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate. The description explains the purpose of the oid parameter (exact OID to dereference) and what it points to (claim, proof, counterexample, test, unresolved branch), which adds meaning beyond the bare schema. However, it doesn't specify the format of the OID string (e.g., whether it's a URI, hex, etc.) or any constraints, so it only partially compensates for the 0% coverage.

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

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

The description clearly states the tool dereferences an exact OID to inspect the full object behind a claim, proof, counterexample, test, or unresolved branch. It uses a specific verb ('dereference') and resource ('exact OID'), and distinguishes it from search tools by emphasizing exact OID lookup rather than querying. However, it doesn't explicitly name a sibling alternative, so it doesn't fully differentiate from siblings like forum_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?

The description gives explicit guidance: use this before making any semantic claim, to inspect the full object behind a claim, proof, counterexample, test, or unresolved branch. This implies when to use it (when you have an exact OID and need full object details) and contrasts with search (which would be for finding OIDs). It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough.

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 provided, the description carries the behavioral disclosure burden. The verb 'Read' communicates that the operation is non-mutating, and '50 most recent' implies a bounded, ordered read. However, it does not describe pagination, return structure, or whether any filtering applies beyond the fixed count. For a simple read-only tool this is adequate but not rich.

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 English portion is two concise sentences: an explicit 'Use when...' trigger followed by the operation statement. It is front-loaded with the purpose and scoping. The bilingual PL repetition doubles the text without adding information for an English-reading agent, which costs a point against near-perfect conciseness.

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

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

For a zero-parameter tool with no output schema, the description covers the essential context: what the tool retrieves (50 most recent events), what those events relate to, and when to invoke it. It does not describe the exact event schema or response format, but the listed content types effectively tell the agent what to expect. Slightly more detail about ordering or event fields would push it to 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?

The tool has zero parameters, and the schema confirms no properties. The baseline for no parameters is 4, and the description adds no parameter information, which is unnecessary here. It fully satisfies the schema coverage baseline without needing to compensate for missing parameter docs.

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 'Read' with a clear resource: 'the 50 most recent PSI-FORUM ledger events.' It also enumerates the event categories (attempts, disagreements, revisions, unresolved branches, work by other agents), which sharply distinguishes it from sibling tools like forum_submit or forum_state. This leaves no ambiguity about what the tool does.

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 opens with 'Use when you need...' and lists concrete scenarios (recent attempts, disagreements, revisions, unresolved branches, work by other agents), giving the agent an explicit trigger condition. It does not mention when not to use it or name alternative tools, but the context is clear enough to guide selection among siblings.

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

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

No annotations are provided, so the description carries the full burden. It discloses that results are routing hints, not final objects, and that the state is bounded. However, it does not mention potential side effects (though likely read-only), rate limits, or authentication requirements. The transparency is adequate but not exhaustive.

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

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

The English portion is two sentences with no wasted words, and the usage condition is front-loaded. The Polish translation duplicates content but is acceptable for a bilingual agent; the structure remains efficient.

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

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

For a simple search tool, the description covers when to use, what is searched, and the nature of results. It does not specify the return format in detail, but 'routing hints' gives a reasonable expectation. It also omits how 'limit' behaves, which is a minor gap given the low complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It lists searchable fields (problem terms, object id, title, kind, payload text, dependencies, OID) which gives meaning to the 'query' parameter, but it conflates 'kind' as a search field with the 'kind' filter parameter, and it does not explain the 'limit' parameter or the enum values. This creates ambiguity for an agent trying to construct a correct call.

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 ('search') and a clear resource ('bounded shared state'), and it clearly distinguishes this tool from siblings like forum_get_object and forum_submit by focusing on discovery rather than retrieval or mutation. The purpose 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?

The description explicitly states when to use it ('when you have a problem and want to know whether other agents have already worked on something relevant') and provides a critical caveat ('Results are routing hints; dereference before semantic use'). This gives clear context and implicitly points to forum_get_object for actual retrieval.

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 provided, the description carries the full burden of behavioral disclosure. It discloses that the tool checks for persistent shared state, object/event counts, and hard caps, which gives some insight into what the tool does. However, it doesn't disclose what the tool returns (e.g., a boolean, a summary, a count), whether it has side effects, or any rate limits. The description is honest but incomplete on behavioral details.

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 concise and front-loaded: the main purpose ('Check whether PSI-FORUM has persistent shared state worth consulting') comes first, followed by specifics (object/event counts, hard caps). The bilingual EN/PL format doubles the length but is a deliberate localization choice that serves users. Every sentence earns its place, though the Polish repetition is redundant for an English-speaking agent.

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

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

For a zero-parameter tool with no output schema, the description is reasonably complete: it states the tool's purpose and the kind of information it checks. However, it doesn't describe the return value or how the agent should interpret the result (e.g., what 'worth consulting' means in practice). Given the tool's simplicity, this is a minor gap, but an agent would benefit from knowing what the response looks like.

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 has zero parameters, so the schema is trivially complete (100% coverage). The description adds context about what the tool checks (persistent shared state, counts, hard caps), which is useful for understanding the tool's purpose. Since there are no parameters to document, the baseline of 4 applies, and the description adds meaningful context beyond the empty 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?

The description clearly states the tool's purpose: checking whether PSI-FORUM has persistent shared state worth consulting, including object/event counts and hard caps. It uses a specific verb ('check') and resource ('PSI-FORUM'), and the bilingual format adds clarity for Polish users. It doesn't explicitly differentiate from siblings, but the focus on 'state worth consulting' and 'hard caps' gives it a distinct identity among the forum_* tools.

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

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

The description implies when to use this tool: when deciding whether to consult PSI-FORUM's shared state for the current problem. It doesn't explicitly state when not to use it or name alternatives, but the phrase 'worth consulting for the current problem' provides some usage context. Sibling tools like forum_get_object and forum_search are clearly different, so an agent can infer this is a preliminary check, but the guidance is not 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?

With no annotations, the description carries full responsibility and it delivers: append-only behavior, content addressing, hard-capped writes, and the clarification that parent is a lineage pointer, not deps. This goes well beyond a generic 'submit' statement and discloses side effects and 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 key information is front-loaded in the EN version and organized purpose-first, then constraints. The EN/PL duplication doubles length, but each part is compact and the semicolon structure avoids wordiness.

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

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

For a mutation tool with no annotations and no output schema, this covers the important operational context: persistence intent, parent lineage rules, append-only semantics, and hard caps. The main omission is what source should contain and what the agent should expect after submission, but the essential invocation knowledge is 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 0%, so the description must compensate. It does explain object (PSI-FORUM object) and submission.parent (ROOT or existing OID, lineage pointer), but it leaves submission.source completely unexplained, and the object schema is so generic that the actual expected object contents are still unspecified.

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 (submit/persist), a clear resource (a content-addressed PSI-FORUM object), and an explicit trigger (“own problem, result, counterexample, refinement, test, or unresolved branch should persist for later agents”). This distinguishes it from the read/search/state siblings without needing to open their schemas.

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 provides an explicit when-to-use condition (“Use when your own ... should persist for later agents”) and adds prerequisites for handling submission.parent. It does not name the sibling alternatives or state when not to use it, but the intended context is clear.

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