GAIP Broker

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds the material behavioral fact that no agent call is made, which is more specific than a generic read-only hint. It does not disclose return format or error behavior, but the annotations lower the burden.

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 sentence with no filler and the key constraint ('without calling the agent') placed at the end after the core purpose. The title reinforces the resource without redundancy.

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 is sufficient for basic invocation with the required agent_card parameter, but it leaves source_url unexplained and 'assess' ambiguous regarding output or evaluation criteria. The sibling names hint at overlap, yet the description does not disambiguate them.

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 for the bare parameter types. It maps 'Agent Card metadata' to agent_card but does not explain the nested object's expected shape or the meaning/optionality of source_url.

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 clear verb ('Assess') and a specific resource ('supplied public Agent Card metadata'), and it adds the scope constraint 'without calling the agent,' which distinguishes it from agent-invoking tools. However, 'assess' is somewhat underspecified, and no sibling tool is named as the alternative.

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?

There is no when-to-use or when-not-to-use guidance. The phrase 'without calling the agent' states a behavioral constraint rather than a selection rule, and the description does not point to compare_agent_candidates or any gaip_* sibling as an alternative.

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. The description adds meaningful behavioral context: it is deterministic and performs metadata checks, and it restricts input to public Agent Cards. This goes beyond the annotation baseline and clarifies what the tool actually does.

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 the purpose. It is efficiently written and easy to parse.

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

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

There is no output schema, yet the description does not explain what the ranking output looks like, what 'deterministic task-specific metadata checks' refer to, or how task_class affects behavior. An agent would need additional inference to use the tool correctly and interpret its results.

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 only hints that 'candidates' are supplied public Agent Cards, but it does not explain the structure of the candidate objects or the role of the optional task_class parameter. Most parameter meaning is left undocumented.

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 ('Rank'), a resource ('supplied public Agent Cards'), and a method ('deterministic task-specific metadata checks'). It clearly distinguishes from siblings like assess_agent_card by focusing on ranking multiple candidates rather than assessing a single one.

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: the verb 'Rank' and mention of multiple cards suggest it is for comparing a set of candidates. However, there is no explicit guidance about when to use this tool versus assess_agent_card or the other siblings, and no exclusions or conditions are 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds 'public' and specifies the content (capability and governance boundary), which provides some context beyond annotations. However, it doesn't disclose any other behavioral traits like response format or rate limits. With annotations present, a 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 sentence with no filler. The core purpose is front-loaded: 'Return GAIP's public read-only capability and governance boundary.' Every word earns its place, making it highly concise and structured.

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, no-output-schema tool with annotations covering safety, the description is sufficient. It states the purpose clearly and the scope. It could elaborate on what 'capability' includes, but that's a minor gap given the tool's simplicity and the presence of sibling tools that cover specific aspects.

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 is trivially complete at 100% coverage. The description need not explain parameters, and the baseline for 0 params is 4. The description adds nothing about parameters, but none exist, so this score is fair.

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

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

The description states the verb 'Return' and the specific resource: GAIP's public read-only capability and governance boundary. This clearly distinguishes it from sibling tools like gaip_get_governance_limits, which focuses on limits, and gaip_get_identity_and_registry_status, which covers identity/registry. The scope is explicit and actionable.

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 provided on when to use this tool versus its siblings. The description only states what it does, without mentioning alternatives or conditions that would select it over gaip_get_governance_limits or other getters. An agent would have to infer usage from the name alone.

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. The description adds the specific content of the return (Phase-1 external-participation policy) and notes it is machine-readable, which provides useful context beyond the annotations. However, it does not detail the structure or format of the policy.

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, front-loaded sentence with no extraneous words. It states the action, the subject, and a key qualifier ('machine-readable') efficiently.

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's simplicity (no parameters, no output schema), the description adequately conveys what is returned. It is a straightforward getter, and the description provides sufficient context for an agent to know what it will receive, though it does not enumerate policy fields.

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 description does not need to explain any. Per the baseline for zero-parameter tools, this score is appropriate; the schema coverage is trivially 100% and there is nothing to add.

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 ('Return') and identifies the resource as the 'Phase-1 external-participation policy,' which clearly distinguishes it from sibling tools like gaip_get_capabilities or gaip_get_shadow_status. The phrase 'machine-readable' also clarifies the return format.

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 on when to use this tool versus alternatives. The description only states what the tool does, with no mention of context, exclusions, or when another sibling might be more appropriate.

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 doesn't need to restate those traits. It adds the return focus on activation states and blockers, but says nothing about auth requirements, rate limits, caching, or additional behavioral caveats; the word 'truthful' is not operationalized.

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 tight sentence with a front-loaded verb and object. The adjective 'truthful' is slightly vague and could be considered filler, but overall the structure is efficient and readable.

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 zero parameters and strong safety annotations, the enumeration of activation states and blockers gives the essential semantic content. It lacks return format or error details, but for a simple status read this is close to sufficient.

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

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

The tool has zero parameters and schema description coverage is 100%, so there is no parameter-semantics burden on the description. Baseline 4 applies because there is nothing to clarify.

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 specific verb 'Return' and enumerates precise resources: A2A, MCP, Entra Agent ID and ERC-8004 activation states and blockers. It clearly states what the tool does, but does not explicitly distinguish itself from sibling getters like gaip_get_capabilities or gaip_get_shadow_status.

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 intended usage is implied by the tool name and return content: an agent would infer to use it when identity/registry activation status is needed. However, there is no explicit when-to-use, when-not-to-use, or comparison to sibling tools, leaving routing partly 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 declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the key behavioral context that 'Shadow activity is not live execution,' which clarifies the nature of the data and prevents confusion with execution-status tools. This goes beyond the annotations, so a 4 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 stating the purpose, followed by a brief, relevant clarification. Every word earns its place, with no redundancy or fluff.

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, no-output-schema tool, the description is sufficiently complete: it states what is returned (latest public shadow-planning status) and clarifies the key distinction from live execution. The return format is not detailed, but that's a minor gap given the tool's simplicity and the absence of an output schema.

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?

There are no parameters, so the schema trivially covers 100% of them. The description adds no parameter-specific information, but none is needed. The baseline for zero-parameter tools is 4, which is met 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?

The description clearly states the verb ('Return') and the specific resource ('latest public shadow-planning status'), making the tool's purpose unambiguous. It distinguishes itself from the sibling gaip_get_* tools by focusing on shadow-planning status, and the clarification that it's not live execution further differentiates it from execution-related 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 you need shadow-planning status) and clarifies what it is not (live execution), but it does not explicitly name alternatives or give conditions for choosing another tool. The guidance is implicit rather than explicit, leaving some inference to the agent.

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 mark this as read-only and idempotent. The description goes beyond that by specifying that only 'allow-listed public fields' are returned and that the receipt must be 'retained,' which clarifies access and availability 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?

A single front-loaded sentence states the operation, scope, and lookup requirement with 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 one-parameter idempotent read with annotations covering safety, the description is sufficient: it tells the agent what it will get (allow-listed public fields), the precondition (retained), and how to look it up (exact id). No output schema is required for this simple case.

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 has no property descriptions (0% coverage), but the description compensates by explaining that receipt_id is used as an exact identifier rather than a fuzzy search key. This adds meaning above the bare string type and length constraints.

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 uses a specific verb ('Retrieve'), identifies the resource ('public GAIP receipt' / 'allow-listed public fields'), and states the lookup mode ('by exact id'). This clearly distinguishes it from governance, capabilities, and shadow-status 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?

'By exact id' and 'retained receipt' clearly indicate when to call this tool: when the agent has the exact identifier and only needs the exposed public fields. It does not name an alternative tool for the same operation, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the key behavioral constraint that acceptance criteria must be 'explicit deterministic' – implying non-deterministic or subjective criteria are not suitable. However, it does not disclose what the tool returns (e.g., pass/fail, details) or how it handles missing fields, which would be useful for a verification tool.

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

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

The description is a single sentence with no wasted words. It front-loads the action ('Verify') and the key constraint ('explicit deterministic acceptance criteria'). Every word 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?

Given the tool has nested objects, 0% schema description coverage, and no output schema, the description is too thin. An agent needs to know the shape of acceptance_criteria items (e.g., how to express expected values, comparison operators) and what the verification result looks like. The description leaves these critical details to inference, making it incomplete for reliable invocation.

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 for parameter meaning. The description mentions 'result' and 'acceptance criteria' generically, but it does not explain the structure of acceptance_criteria items (e.g., field, expected value, operator) or what the result object should contain. The schema only requires 'field' on each criterion, leaving the rest of the semantics unexplained. This is a significant gap for a tool with nested objects.

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 ('verify') and resource ('a supplied result') against 'explicit deterministic acceptance criteria', which clearly distinguishes it from sibling tools like assess_agent_card or compare_agent_candidates. It is clear but does not explicitly name a sibling or differentiate beyond the core action.

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: use this tool when you have a result and deterministic acceptance criteria to check. It does not explicitly state when not to use it or mention alternatives, but the context of verification against deterministic criteria is reasonably clear. No exclusions or alternative routing are provided.

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