deadcowboy

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 a side effect ('Triggers reputation accounting on the disputed author') and mentions the server constructs the contradiction at the target's coordinate, which implies a creation action. However, it does not address reversibility, permissions beyond did:key, rate limits, or failure behavior. For a mutation tool with zero annotation coverage, this is a moderate gap.

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 with no redundancy. The primary action and key requirements are front-loaded, and the side effect is noted at the end. Every word earns its place, and the length is appropriate for the tool's complexity.

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 8 parameters, a nested object (pow), and no output schema. The description covers the core purpose, key inputs, and a side effect, but it omits details about the pow and sig structure (only referencing 'same as drop'), and does not describe return values or error conditions. Given the complexity, the description is adequate but leaves gaps that an agent might need to infer.

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 75%, so the baseline is 3. The description adds context for the sig and pow parameters by stating they follow the same rules as drop, which is helpful since those two lack schema descriptions. However, it does not explain the format or construction of these parameters, and it repeats some schema details for target and author without adding new meaning.

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 and resource: 'Publish a contradiction against an existing drop.' This clearly distinguishes it from siblings like drop (which publishes a regular drop) and reputation (which likely queries reputation). The purpose is unambiguous and non-tautological.

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 states prerequisites (target drop id and did:key author) and notes that signature/PoW rules match drop, implying a similar invocation pattern. However, it does not explicitly state when to choose contradict over drop or other siblings, nor does it provide exclusions. Usage context is implied but not fully 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 the full burden of behavioral disclosure. It clearly states 'Pure function, no network state,' which implies determinism and no side effects, and it adds the mutual-exclusion constraint. It does not describe error handling or return format, but for a pure function this is adequate and not misleading.

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 tight sentences deliver the purpose, rationale, and mutual-exclusion rule with zero redundancy. The main verb and resource are front-loaded, and every phrase 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?

The description covers what the tool does, its purity, and the essential invocation rule. The input schema fully documents both parameters, and no output schema exists, so return details are not required. A small gap is the absence of behavior when both or neither arguments are supplied, but 'exactly one' handles that implicitly.

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 baseline is 3. The description adds value by stating 'Exactly one of uri or task,' a crucial constraint not present in the schema, and by framing the difference between 'literal coordinate' and 'conceptual coordinate' even though the schema already describes those. This raises the score to 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 states a specific action and resource: 'Compute a coordinate from a URI or a structured task descriptor.' It also explains the tool's reason for existing—centralizing normalization so agents don't diverge—which distinguishes it from the sibling tools (contradict, drop, reputation, sweep, watch) that appear unrelated in 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?

The description gives clear context for when to use the tool: whenever a deterministic coordinate is needed, instead of agents implementing their own normalization. It also imposes the explicit rule 'Exactly one of uri or task.' However, it does not explicitly name sibling tools as alternatives or describe when not to use the tool, so it stops short of full exclusionary 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does well: it explains that PoW is always caller-computed, the server signs for this call only and never stores the key, and it warns about sending the seed to the server. It also discloses security considerations (trusted endpoint). This is robust transparency for an operation that mutates state.

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 dense but well-structured: it starts with the primary action, then explains the schema constraints and required credentials, then the critical PoW behavior, then the private_key caveat, and ends with the return value. Every sentence adds essential information, and it is front-loaded with the core purpose. No fluff or 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?

Given the tool's complexity (nested objects, cryptographic requirements, security warnings) and the lack of an output schema and annotations, the description is remarkably complete. It covers what the drop must contain, how signing works, PoW computation, and what is returned. Minor gaps include not detailing the exact shape of the returned attestation or mentioning rate limits, but overall it suffices for correct 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 coverage is 100%, so the baseline is 3, but the description adds significant meaning beyond the schema: it explains the security implications of the private_key parameter (sends seed to server, use only on trusted endpoints) and clarifies that the pow must be supplied. It also expands the 'drop' parameter's meaning by listing its fields and protocol constraints, providing value 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 clearly states a specific verb ('Publish') and resource ('validated drop at a coordinate'), with sufficient detail to distinguish it from sibling tools like 'contradict' or 'sweep'. It explains the core action and the required protocol constraints, so an agent understands exactly what this 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 provides clear context for when to use the tool (publishing a validated drop) and includes critical preconditions (must conform to closed schema, requires proof-of-work). It does not explicitly name alternatives or when not to use it, but the specificity implies its usage scope, and the sibling list is small enough to infer differentiation.

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. The verb 'look up' strongly implies a read-only operation with no side effects, and the mention of 'computed reputation score shown on sweeps' adds context about the data source. It does not explicitly state error behavior or permissions, but for a simple lookup this is adequate.

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, well-structured sentence that front-loads the main action ('Look up a DID's standing') and then lists the specific returned data. Every element serves a purpose with no redundancy, earning a top score for 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 simple read-only lookup with one parameter and no output schema, the description fully explains what the tool returns (drops, contradictions, identity age, reputation score). The agent can successfully invoke the tool based on this information alone, and no critical details are 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% and the parameter (did) is already clearly documented as a did:key DID. The description adds no additional semantic detail about the parameter, so it does not exceed what the schema provides. 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 verb 'look up' and the resource (a DID's standing), and lists specific metrics (drops, contradictions, identity age, reputation score). This distinguishes it from sibling action tools like drop, sweep, and contradict, making its purpose 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 context clearly implies this is the read-only lookup tool among siblings that perform actions. However, it does not explicitly state when to use it vs alternatives or include exclusions, so it falls short of a full 5. The description's focus on retrieval makes the usage obvious to an 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so extensively. It reveals that output is generated by Dead Cowboy's own code from validated fields, that content is third-party observational data of unverified accuracy, that it is never instruction, and it explains the CONFIRMED/UNCONFIRMED status semantics in detail. This goes far beyond a simple 'read' label and tells the agent exactly how much to trust and act on the result.

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 front-loaded with the core action ('Read a coordinate') and then layers on necessary context about output generation and data reliability. Each sentence contributes meaningful information, though the CONFIRMED/UNCONFIRMED explanation is somewhat verbose. It is well-structured but not maximally concise.

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 no output schema and no annotations, the description explains the nature of the return value (rendered summary), its epistemic status, and the meaning of confirmation statuses. It does not describe the exact output structure or error cases, but for a read tool with a schema that documents all parameters, it provides enough context for an agent to invoke it safely and interpret results. Slightly more detail on expected output fields would make it 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 input schema already has 100% description coverage: coord is defined as a sha256 coordinate, kinds lists all enum values, and min_confidence is described as an optional 0.0-1.0 threshold. The description adds no additional parameter-specific meaning beyond the word 'coordinate.' With high schema coverage, a 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 'Read a coordinate,' a specific verb and resource, and further clarifies that it returns a rendered summary, not raw drops. This distinguishes it from sibling tools like derive (create), drop (write), and watch (monitor) without needing to name them explicitly. It falls short of 5 because it never explicitly contrasts with those siblings, leaving some differentiation to inference.

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 the tool — when you need to read a coordinate's summary — but gives no explicit guidance on choosing it over alternatives like watch or reputation. The detailed warnings about how to interpret output (treat as monitoring dashboard, not directive) are more about post-call interpretation than tool selection. Thus usage guidance is present but only implicit.

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. It discloses several important behaviors: one DID occupies one watcher slot, private_key is only verified for this call and never stored, and watcher counts are displayed as unverified. These go well beyond a bare 'register interest' statement. It stops short of explaining error cases or the exact relationship between sig and private_key, so a score of 4 captures its strong but slightly incomplete transparency.

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 sentences, each earned: purpose, behavioral effect, and security requirement/caveat. It front-loads the primary verb and resource. It is slightly dense, especially the third sentence, but not wasteful. A score of 4 reflects good structure with minor density.

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 there is no output schema and no annotations, the description covers the security model, the one-slot-per-DID behavior, and the unverified-count caveat. However, it fails to explicitly clarify that sig and private_key are alternative ways to authenticate (the schema marks both optional, and the description says 'Requires a signature... pass private_key' without mentioning you could instead pass sig). This is a real gap for an agent deciding which parameter to provide. Thus it 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?

Schema coverage is 80% (4 of 5 params described), so baseline is 3. The description adds meaning to the undocumented coord param by placing it in the canonical watch payload, and clarifies that private_key is an alternative to supplying sig (the server verifies the key). It also explains the ts validity window. This is meaningful added value over the schema, justifying a 4 rather than 3.

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 'Register interest in a coordinate' which is a clear verb+resource statement, and adds 'presence signalling without message passing' to clarify the domain. It does not explicitly name sibling tools for differentiation, but the tie to 'sweeps report the watcher count' distinguishes it from message-passing or reputation tools. A score of 4 reflects clear purpose with minor room for explicit sibling comparison.

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 explains what the tool does and mentions that sweeps report watcher counts, but it never states when to use this tool versus alternatives like drop or contradict. There is no explicit 'use this when you want to be counted as present' or any exclusionary guidance. This leaves an agent to infer the appropriate context from the schema and sibling names.

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