Hive Flag

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

No annotations are provided, so the description must disclose behavioral traits. It mentions 'Charges $0.001 USDC' indicating a side effect, but lacks details on idempotency, error conditions (e.g., duplicate flag_key), or response structure. This is insufficient for a creation 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?

Two efficient sentences, front-loaded with the verb and resource. No unnecessary words, all parts earn their place. 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?

The tool has 6 parameters (4 required), moderate complexity, and no output schema. The description does not explain return values, error scenarios, or what happens on success. For a creation tool, this is a significant gap. Completely lacks behavioral context beyond the basic action.

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 50% (3 of 6 params described). The description adds that the flag includes default value and targeting rules, and for 'targeting_rules' it references a README. This adds some meaning beyond the schema, but does not fully compensate for missing param descriptions. Baseline 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 clearly states the action 'Create a flag' with key components (default value, targeting rules) and adds a unique cost detail. It effectively distinguishes from sibling tools (delete, describe, eval, list, update) which perform different operations.

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 provides context (cost) but no explicit guidance on when to use this tool vs alternatives. However, given that siblings are distinct actions, usage is mostly clear. A more explicit 'when to use' statement would improve the score.

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 must disclose behavioral traits. It mentions charges ($0.001 USDC on Base), but it does not specify irreversible effects, required permissions, or return value. The term 'tombstone' is ambiguous without clarification.

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 very concise with two short sentences. Every word adds value: 'tombstone' indicates the action, 'Owner DID only' constraints usage, and the cost is stated. No verbose or redundant phrases.

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 3 parameters (2 required), no output schema, and no annotations, the description is inadequate. It omits what 'tombstone' means, what the output is, and what 'tx_hash' is used for. Only cost and owner constraint are provided.

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 hints that 'owner_did' is for the owner's DID, but it does not explain 'flag_key' or the optional 'tx_hash'. The description adds minimal meaning beyond the parameter names.

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 'Tombstone' to indicate deletion/marking inactive, and it is clear that the tool operates on a flag resource. It distinguishes from siblings like flag_create and flag_update, but 'tombstone' is somewhat jargon, so clarity could be improved.

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 mentions 'Owner DID only' as a usage constraint, but it does not provide guidance on when to use this tool versus alternatives like flag_update or flag_describe. No when-not-to-use or alternative tools are mentioned.

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, description carries full burden. It discloses read-only nature and 'no charge', and lists return elements. Missing details on error behavior, authorization, or response format, but provides sufficient context for a simple retrieval 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?

Two sentences, no fluff. Purpose and key traits are front-loaded. Every sentence serves a distinct function.

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 adequately covers purpose, return contents, and behavioral implications. No output schema needed given the listed return elements.

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 has 0% description coverage on the single parameter. Description adds meaning by indicating flag_key identifies the flag, compensating for the schema gap.

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?

Clearly states verb 'Return' and resource 'full definition of a flag', listing specific attributes (type, default value, targeting rules, evaluation count). Contrasts with sibling tools like flag_create, flag_delete, flag_eval, flag_list, flag_update, establishing distinct read-only purpose.

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?

Specifies 'Read-only, no charge', implying safety, but does not explicitly guide when to use vs. alternatives or provide exclusion criteria. The differentiation from siblings is implicit through naming, not stated in description.

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 full burden. It discloses the cost ($0.0005 USDC on Base) and the return value (flag value and targeting rule). However, it does not mention idempotency, authentication requirements, or potential side effects.

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 sentences, front-loaded with the purpose, and includes the cost as a separate sentence. No superfluous information.

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 no output schema and no annotations, the description covers the core action and cost but fails to clarify the role of the optional tx_hash parameter (e.g., whether payment is required). This omission could lead to confusion.

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 describes the parameters. The description adds no additional meaning beyond what is in the schema; it only hints at the output, not parameter details.

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 action: evaluating a flag for a DID, returning the resolved value and the targeting rule that matched. It also mentions the cost. This distinguishes it from sibling CRUD tools like flag_create and flag_delete.

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 for evaluation but does not explicitly provide guidance on when to use this tool versus alternatives like flag_describe or flag_list. No exclusions or prerequisites are mentioned.

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 description explicitly states the tool is read-only and has no charge, which is useful behavioral context beyond the lack of annotations. No contradictions found.

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 extremely concise at two sentences, with no superfluous words. Information is front-loaded 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?

For a simple list tool with one parameter and no output schema, the description is largely adequate. It could mention the output format, but the request is minimal so this is acceptable.

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?

With 100% schema coverage, the description adds no extra meaning beyond the parameter description. The baseline of 3 is appropriate as the schema already provides necessary semantics.

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 'list' and the resource 'flags owned by a DID', making the purpose unambiguous. It distinguishes from sibling tools like flag_create or flag_delete.

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 includes 'Read-only, no charge', indicating when it's safe to use. However, it does not explicitly guide when to prefer this over flag_describe or other alternatives.

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?

Without annotations, the description carries the full burden. It discloses the action (update), owner constraint, and cost, but does not explain atomicity, side effects, or reversibility. The cost is a positive disclosure, but more detail on behavior is missing.

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 sentences, front-loading the purpose and then adding constraints. Every sentence adds essential information with no 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 covers purpose, owner requirement, and cost, but lacks details on return values, error handling, and the role of 'tx_hash'. Given the cost implication and moderate schema complexity, more completeness is needed.

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 40%. The description adds that 'default_value' and 'targeting_rules' are the update targets, and the schema clarifies they can be omitted. However, 'tx_hash' and 'flag_key' lack explanations, and the description does not compensate fully.

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: 'Update a flag's default value or targeting rules.' This is a specific verb+resource combination, and the mention of 'Owner DID only' and cost distinguishes it from siblings like flag_create or flag_delete.

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 provides context by stating 'Owner DID only' and the cost, implying that only the owner should use it. However, it does not explicitly note when not to use it or contrast with alternatives, leaving room for confusion.

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