Contribution Exchange

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

Beyond the readOnly/idempotent annotations, the description adds meaningful behavioral guarantees: it is read-only, does not propose/commit/authorize anything, and explicitly discloses HTTPS enforcement, redirect limits, timeouts, and SSRF protections including blocked network targets. This is valuable, non-redundant context.

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 sentences, front-loaded with the core purpose, followed by return contents, safety, and security constraints. Every sentence adds distinct information with 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?

The description covers purpose, return content, and important behavioral/security constraints, which is strong given the single parameter and supportive annotations. It does not detail the exact response schema or edge cases like what happens when a domain has no profile, but these are not critical for an agent to invoke 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?

Schema coverage is 100% and the single 'domain' parameter is already well described, including normalization to hostname. The description adds no new parameter-level meaning, so the baseline score of 3 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 opens with a specific verb and resource: 'Determine whether a domain publishes a Contribution Exchange profile.' It distinguishes itself from the get_* siblings by stating it returns the canonical manifest, policy URLs, signal URLs, and hosting mode, making its discovery role 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?

The description clearly implies this is the entry-point discovery tool for a domain's Exchange profile, and the sibling names (get_policy, get_signal, etc.) suggest follow-up actions. It does not explicitly state when not to use it or name alternatives, but the context is strong enough for an agent to select it appropriately.

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 readOnly, idempotent, and non-destructive behavior, and the description adds significant non-obvious context: visibility enforcement, that verification is Steward-controlled and cannot be self-asserted, and that attempt status is distinct from exchange state. This goes well beyond the structured 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 compact, front-loaded with the core purpose, and every sentence adds meaningful information. There is no filler or repetition of schema details.

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 two-parameter read operation with rich annotations, the description covers what the tool returns, when data may be absent, access restrictions, and domain-specific caveats. No critical information an agent needs to invoke it correctly 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% because both signal_id and attempt_id are documented as IDs with length constraints. The description does not add extra parameter-level meaning, so the baseline of 3 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 opens with a specific verb and resource: 'Get detail for a signal attempt.' It further distinguishes the target by noting 'Attempt status is NOT an exchange state' and by focusing on 'verification result,' which separates it from sibling tools like exchange_get_signal and exchange_get_policy.

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 clearly implies this is the read-only way to retrieve attempt detail and provides important access context ('actors may only read their own private attempts'), but it does not explicitly name alternatives or state when to use another sibling tool. Usage guidance is present but mostly implied.

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?

Beyond the annotations, the description adds meaningful behavioral context: it returns authority ceilings, consideration limits, human-review requirements, and supported behavior, and it distinguishes a missing policy from an unavailable service. This helps the agent interpret results correctly.

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 three focused sentences, with the primary verb and resource front-loaded. Every sentence adds useful information and there is no repetition of schema or annotation details.

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?

Even without an output schema, the description enumerates the returned policy dimensions and error-relevant behavior. Combined with the annotations, this gives an agent enough to call the tool and interpret its result.

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 already fully describes the only parameter, 'domain', with 100% coverage. The description adds some context with 'domain or its delegated Steward' but provides no new format or value constraints, so it stays at the baseline.

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

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

The description names a specific verb ('Fetch'), a clear resource ('canonical Contribution Exchange policy'), and the valid targets ('a domain or its delegated Steward'). It also lists what the tool returns, which distinguishes it from sibling tools like exchange_preflight and exchange_get_signal.

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 that the tool is read-only and does not perform preflight evaluation, which tells an agent when not to use it. It does not explicitly name sibling alternatives, so it stops short of fully explicit 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?

Annotations already establish read-only, idempotent, and non-destructive behavior, but the description adds domain-specific transparency by listing what the response includes and by explicitly stating that a signal does NOT create a Commitment, authorize execution, or guarantee payment. This meaningfully goes 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?

The first sentence is front-loaded with the core purpose, and the final sentence provides valuable behavioral context. The standalone 'Read-only.' sentence is slightly redundant with the readOnlyHint annotation, so not every sentence fully 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 output schema, the description compensates by enumerating the components of the returned signal and by clarifying what the signal does not do. For a single-parameter read-only getter, the remaining operational context is sufficiently 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 100% and the schema already documents signal_id as 'Signal ID.' The tool description adds Exchange Signal context, but no additional parameter semantics or format guidance beyond what the schema provides.

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 opening sentence states a specific verb ('Get'), resource ('Exchange Signal'), and access pattern ('by ID'), clearly distinguishing this from sibling exchange_list_signals. The title reinforces the same purpose with 'Signal Detail by ID'.

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 makes the usage context clear: use when you need the full detail of a single signal known by ID. It does not explicitly mention alternatives such as exchange_list_signals, so when-not-to-use guidance 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?

Beyond the readOnlyHint annotation, the description adds crucial behavioral context: it explicitly warns that signal status is distinct from exchange status and that a signal does not create a Commitment or authorize execution. It also discloses the key returned attributes (canonical URLs, revision, revision hash, status), which is valuable since there is no output schema.

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, front-loaded with the action, and every sentence earns its place: scope, safety, return contents, and the important status-semantics caveat. No filler or redundant restatement of the schema is present.

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 list tool with 11 parameters and no output schema, the description covers the essential scope, return keys, and a critical semantic warning about signal vs exchange status. It relies somewhat on the HTTP API reference for exact filter behavior, but the schema already documents all parameters, so an agent has enough context 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?

Schema description coverage is 100%, so the parameters are already fully documented in the input schema. The description adds only a general statement that the same filters and pagination as the HTTP API are supported, which does not deepen the meaning of any specific parameter 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?

The description uses a specific verb ('List'), identifies the exact resource ('domain-published Exchange Signals'), and enumerates the signal types. It clearly differentiates this listing operation from the sibling get/discover/preflight tools, especially because it emphasizes the list scope and the returned fields.

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 listing signals and notes that it supports filters and pagination, but it does not explicitly contrast alternatives such as exchange_get_signal for a single signal. The usage context is present but no when-not-to-use or sibling 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?

Even with readOnlyHint and idempotentHint annotations already present, the description adds meaningful behavioral detail: 'performs no proposal insertion, notification, event creation, or state transition' and notes that results are 'advisory and time-bound.' This goes beyond what annotations convey and sets accurate expectations about side effects and reliability.

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 compact and front-loaded, with the core action in the first sentence and important caveats following. The 'Uses the same evaluateProposal function' sentence adds credibility but is somewhat optional, and the READ-ONLY phrasing slightly overlaps with the explicit no-state-transition list.

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?

Without an output schema, the description still communicates the main outcome classes and clarifies side effects and non-guarantees. It does not specify the exact response shape or fields, but an agent has enough context to select and invoke 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?

Schema description coverage is 100%, so the schema already documents every parameter. The tool description adds no parameter-level meaning beyond what the schema provides. For fully covered schemas, 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?

The description opens with a specific verb and resource: 'Evaluate a proposed contribution against the same policy logic used by the real proposal flow.' It also lists the distinct possible results (auto-engaged, accepted, escalated, rejected), making it easy to distinguish from sibling getter/discovery 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 clearly frames this as an advisory, pre-flight check and explicitly warns that favorable results do not guarantee commitment, authorization, payment, or execution. It does not name specific alternative tools for when a non-preflight action is needed, but the sibling tool names and the READ-ONLY framing make the intended use clear.

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