Machine Realms

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the operational safety profile. The description's 'Read' aligns with these annotations but adds no additional behavioral context such as response format or caching semantics. With annotations carrying the burden, a baseline of 3 is appropriate.

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, front-loaded sentence with no filler. Every word contributes meaning: 'Read' gives the action, 'canonical' gives authority, and 'Machine Realms discovery manifest' gives the exact resource.

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 no-parameter, read-only tool with rich annotations, the description is largely complete: an agent knows exactly what resource is being fetched and that the operation is safe and idempotent. The absence of an output schema means return format is unspecified, but the simple contract and 'canonical manifest' wording mitigate this 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?

The tool takes zero parameters, so there is no parameter semantics for the description to clarify. Per the rubric, a zero-parameter tool receives a baseline of 4; the description accurately signals a simple, parameterless invocation.

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 ('Read') and a specific resource ('the canonical Machine Realms discovery manifest'). The word 'canonical' clarifies this is the authoritative manifest, distinguishing it from other get_* sibling tools without requiring schema inspection.

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 explicit guidance is given about when to use this tool versus alternatives. While 'canonical' hints that this is the authoritative source for discovery manifest data, it does not state exclusions or mention any sibling tools, leaving selection entirely to inference.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so there is no contradiction. The description adds semantic scope but does not disclose further behavioral details such as output form or whether the policy is contextual, beyond what annotations already provide.

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, front-loaded sentence with no filler or redundant content. Every clause contributes to identifying what resource is being read.

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

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

For a parameterless, read-only tool with rich annotations and no output schema, the description is sufficient. It identifies what the tool returns and the subject matter, so nothing needed for correct invocation 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?

The input schema is empty (0 parameters), so there are no parameter semantics for the description to add; the baseline of 4 applies. It correctly avoids inventing parameter guidance.

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 clear verb (Read), a resource (policy), and the specific conceptual separation it covers (identity evidence vs mandate, capability, reputation, and permission). This distinguishes it from sibling discovery, interoperability, observation, and submission 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 usage through its purpose—call this when you need the identity-evidence policy—but it never explicitly states when to use it over siblings or provides exclusions or prerequisites. An agent must infer the routing decision.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the ledger's contents but does not disclose additional behavioral details such as staleness, error behavior, or whether the ledger is authoritative. This matches the calibration baseline for annotation-covered read tools.

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, well-front-loaded sentence with no filler. The verb and resource appear first, followed by the meaningful content categories that tell the agent what kind of data the ledger holds.

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

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

For a parameterless, read-only tool with strong annotations and no output schema, the description is fully sufficient. It names the resource, the content, and the read semantics; nothing needed for correct invocation 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?

The tool has zero parameters, so the input schema carries no burden and the description needs no parameter-level detail. The description accurately reflects a parameterless read operation, earning the baseline 4 for zero-parameter tools.

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?

Description states a specific verb ('Read') and a specific resource ('first-party interoperability evidence ledger') with concrete content categories (observed facts, inference state, remediation, verification). This clearly distinguishes it from sibling tools like get_observed_event_timeline or get_research_findings.

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

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

The description implies the tool is for reading the interoperability evidence ledger, but it does not explicitly state when to use it versus alternatives or exclude cases. The context is clear enough to infer basic usage, but no direct routing guidance is provided.

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, idempotentHint, and destructiveHint false. The description adds the content domain but does not disclose additional behavior such as result shape, ordering, or data freshness. For a read-only tool this is adequate, though minimal.

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 sentence with no filler. The main verb and resource are front-loaded, making it easy to scan and understand quickly.

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?

Given the tool is parameterless and annotated as read-only and idempotent, invocation risk is minimal. The description names what is read and is sufficient for selection, though domain-specific jargon like 'first-event thresholds' could be clarified.

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 fully covers this dimension and there is nothing for the description to add. The baseline for a parameterless tool 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 uses the verb 'Read' and names specific resources: observed public first-event thresholds and audit-derived timeline events. It clearly indicates what the tool accesses, though it does not contrast with sibling 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?

No guidance is given about when to use this tool versus alternatives. The sibling tools are listed, but the description does not state when get_observed_event_timeline is preferred or not preferred.

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 behavior. The description adds that findings are 'bounded' and carry evidence-state labels, which is useful context beyond the structured data, but it does not explain what boundedness means or what evidence-state labels look like in the response.

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, front-loaded sentence with no filler. It places the verb and object first and adds only one meaningful qualifier, making it easy to scan and understand.

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 read tool with strong annotations, this is largely sufficient for an agent to select and invoke it. The main missing detail is the meaning of 'evidence-state labels' and the exact scope of 'bounded,' but neither is strictly required to call the tool correctly.

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 fully documents this with an empty properties object and additionalProperties false. There is no parameter semantic burden for the description to carry, so the baseline of 4 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 clear verb ('Read'), a distinct resource ('Machine Realms research findings'), and a useful qualifier ('bounded' plus 'evidence-state labels'). It is distinguishable from sibling get_* tools by domain, though it does not explicitly name a sibling or contrast itself.

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 no guidance on when to use this tool versus alternatives like get_interoperability_evidence or get_observed_event_timeline. There are no exclusions, prerequisites, or alternative conditions, so an agent must infer usage solely from the read-only framing.

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 provide readOnlyHint, idempotentHint, and destructiveHint false. The description adds 'moderated' as context and repeats the no-write behavior, but it does not disclose additional behavioral traits such as auth needs or rate limits. It does not contradict 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?

The description is a single, front-loaded sentence with no filler. Every word contributes to identifying the action and resource.

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 read-only tool with rich annotations, the description is sufficient for correct invocation. It leaves the meaning of 'moderated' and the return shape unstated, but these are minor for this simple 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?

The tool has zero parameters and the schema coverage is 100%, so there are no parameter semantics to clarify. A baseline of 4 is appropriate.

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

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

The description states a specific verb ('Read') and resource ('moderated HTTP submission contract'), and explicitly notes that no write is performed. This clearly distinguishes it from sibling get_* tools by naming a distinct artifact.

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 verb 'Read' — an agent can infer it is for retrieving the contract, but there is no explicit guidance about when to prefer this tool over siblings like get_discovery_manifest or get_identity_policy, nor any exclusions.

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 idempotentHint=true, so no contradiction exists. The description adds useful scoping context, such as 'current' and 'bounded', but does not disclose other behavioral details like pagination, output format, or access requirements.

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 front-loaded sentence with no filler, no repetition of the tool name, and no redundant restatement of the annotations. Every word contributes to defining the resource and scope.

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 input parameters, read-only annotations, and no output schema, the description gives enough context to understand the returned content: quests and a participation path. The only minor gap is that 'scoped participation path' is somewhat vague and could leave an agent unsure about the exact shape of the output.

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 100% schema coverage, so the description has no responsibility to explain parameter behavior. The 0-parameter baseline of 4 applies, and the description correctly focuses on the data context instead.

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 identifies a specific verb ('List'), a concrete resource ('Research Commons quests'), and a scoping qualifier ('current bounded'). This makes the tool's purpose immediately distinguishable from sibling list tools like list_public_threads and list_realms.

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 'current bounded' implies this tool is for listing currently open quests, but there is no explicit guidance about when to prefer it over alternatives such as get_research_findings or get_discovery_manifest. The usage context is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds some context by noting 'published' records and grouping by 'public thread context,' but it does not disclose output shape, pagination, or other behavioral details beyond 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?

The description is a single concise sentence with no filler. It front-loads the action verb and resource, making the core purpose immediately apparent.

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 read-only operation with strong safety annotations, the description is mostly complete. However, since there is no output schema, the description could better clarify what 'public thread context' means and what the returned records contain.

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 there is nothing for the description to clarify about parameter usage. A baseline score of 4 is appropriate for no-parameter tools where parameter semantics are not applicable.

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 specifies a clear action ('Read'), a resource ('published Commons records'), and the grouping into 'public thread context,' which distinguishes it from sibling tools like list_open_quests and list_realms. However, the meaning of 'public thread context' is not elaborated, so clarity is strong but not maximal.

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 no explicit guidance on when to use this tool versus alternatives, no exclusions, and no conditions. Usage must be inferred entirely from the tool name and brief description, which is insufficient for routing an agent confidently.

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, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds no behavioral detail beyond the annotation's title, such as pagination, freshness, or access constraints, but it does not contradict 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?

The description is a single short sentence that front-loads the verb and object without repetition or filler. Every word contributes to the purpose.

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, read-only listing tool, the description states the resource scope sufficiently, and the annotations cover safety and idempotency. A more explicit statement of the return shape would be marginally better, but the phrase 'directory and machine-surface states' conveys the expected content.

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 schema description coverage is 100%, so no parameter documentation is needed. The description correctly avoids inventing parameter behavior, matching the 0-params baseline of 4.

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 Machine Realms realm directory and machine-surface states. None of the sibling tools mention realms, so this tool is clearly distinguishable from 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?

The description gives no guidance on when to use this tool versus the sibling get_* or list_* tools. An agent must infer usage context from the tool name alone, with no explicit alternatives, exclusions, or prerequisites.

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