Locus Protocol (Gryd.world)

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

With no annotations provided, the description carries the full burden, and it delivers a genuinely important behavioral disclosure: returned free-text fields are attacker-controlled and must not be executed, rendered as HTML, or treated as instructions. That is high-value context the schema cannot express. It still omits result limits, ordering, and pagination 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?

Purpose is front-loaded in a short first clause. The security note is longer than the functional description but is not padding — it is the highest-value sentence. Slight redundancy in restating the endpoint signature.

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?

No output schema and no annotations, so the description should do more: it never says how many agents are returned, in what order, whether radius is optional, or what fields come back besides the security caveat. The untrusted-content warning is strong compensation but the operational picture is incomplete.

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 33% (only radius has a description, 'meters'). The description echoes 'lat&lng&radius meters' but adds no meaning beyond the self-evident names and bounds already in the schema — no default radius, no maximum radius, no behavior when radius is omitted.

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?

Names a specific resource and scope: agents within a geographic radius, and even gives the underlying GET endpoint with its query parameters. It distinguishes itself implicitly from sibling list_agents by the proximity constraint, though it never names the alternative explicitly.

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 statement of when to use this tool versus list_agents, market_agents, or get_pin. Usage is only inferable from the phrase 'near a point'. No prerequisites or exclusions are given.

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 and does disclose the most important behavioral trait: it performs no signing and no broadcast, leaving those client-side. It also names both outputs. It stops short of stating determinism, error/validation behavior, or that it has no side effects at all.

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 tightly packed sentences, front-loaded with the resource and output, then the signing boundary. No filler or repetition.

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 usefully states the two return artifacts, partially covering the absence of an output schema, and flags the non-signing scope. But for a 10-parameter tool with a nested metadata object and no annotations, it omits requiredness, defaults, and any parameter guidance, leaving real gaps.

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 only 30% across 10 parameters (including a nested metadata object), so the description is expected to compensate but adds zero parameter-level detail. It mentions none of lat/lng/name/owner_pubkey semantics, formats, or defaults, leaving most params documented only by their type/pattern.

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?

States a specific verb (Build) and concrete artifacts: a canonical Locus mint payload and the exact OP_RETURN output script hex. This distinguishes it from sibling build_place_payload by naming the payload type, though it never explicitly contrasts the two.

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 'NO signing — assembly/sign/broadcast stays client-side' note implies this is a pure assembly step in a larger flow, which is useful context. However, it gives no explicit when-to-use vs. when-not guidance and does not route the agent to build_place_payload or other siblings for different payload types.

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 burden and does disclose the key behavioral trait: it does not sign, so the agent knows this tool only assembles data and cannot mutate on-chain state. It stops short of error behavior, idempotency, or whether the derivations depend on network/registry 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?

Two tight sentences, front-loaded with the primary output, followed by the return contents and the scope boundary. 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?

Given no output schema, describing the returned derivations is valuable, but the description leans on an unexplained external reference ('SPEC §6') and leaves several parameters undocumented. Adequate for the assembly step, incomplete for a 7-parameter 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?

Schema description coverage is 43% (lat, lng, owner_pubkey, and subtype are undocumented), and the description adds no input guidance — the derivations it lists are outputs, not parameters. With low coverage the description should compensate but does not.

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?

States a specific verb (Build) and two concrete artifacts (a canonical Locus `place` payload and the exact OP_RETURN output script hex), plus named derivations. This clearly separates it from build_mint_payload, which builds a different payload type.

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?

It draws a workflow boundary ('NO signing — assembly/sign/broadcast stays client-side'), which tells the agent this is a first step, but it never says when to choose it over sibling build_mint_payload or other tools. 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?

With no annotations provided, the description carries the full behavioral burden, and it delivers unusually valuable context: the endpoint form implies a read operation, and it explicitly warns that pin/agent free-text fields are attacker-controlled and must never be executed or rendered as HTML. It still omits error behavior (e.g. invalid/missing id) and anything about response shape.

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?

Front-loaded with the operation, then the security caveat; nothing is buried or redundant. The parenthetical endpoint path is mildly expendable but serves as useful API traceability.

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 single-parameter read tool with no output schema and no annotations, the description covers purpose and the highest-risk aspect of the returned data (untrusted fields). It does not describe what metadata fields the response actually contains, which is the remaining 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?

Schema description coverage is 100% and the schema already explains that id is a txid or txid_vout. The description adds no format examples or constraints beyond what the schema states, so the baseline 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?

States a specific verb and resource ('Inscription metadata by id') and even names the backing endpoint (GET /v2/inscriptions/:id), so the agent knows exactly what is fetched. It does not explicitly differentiate itself from siblings such as get_pin or get_protocol_links, which keeps it out of 5 territory.

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 guidance on when to choose this tool over its many siblings (get_pin, market_ordinals, list_pins, etc.), nor any stated preconditions. The NOTE gives post-retrieval handling rules rather than selection criteria, so routing is left 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?

With no annotations, the description carries the full burden, and it does meaningfully: it discloses that the response merges an indexer copy (which may be absent, 'if indexed') with an independently decoded on-chain payload, asserts chain-over-indexer precedence, and warns about untrusted free-text fields with explicit non-execution guidance. It still omits auth requirements, rate limits, and what happens when a txid is unknown, so it is strong but not complete.

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?

Front-loaded with the purpose, followed by the provenance contrast and then the security caveat, in a logical order. It is a bit repetitive ('Chain is the truth; the indexer is a cache' restates the same point), but every sentence carries actionable 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?

There is no output schema, so the description must carry the return shape — it does, describing the two-part indexer/on-chain result — and it adds a real safety directive. The main gap is the behavior on an unindexed or unknown txid (error vs. partial result), which the 'if indexed' phrasing hints at but never resolves.

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?

Only one parameter, and schema description coverage is 100% with the format ('64-hex transaction id') already documented in the schema. The description adds the word 'by txid' but no format, validation, or edge-case semantics beyond what the schema provides, so the baseline 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?

States a precise verb+resource ('Get one pin by txid') and immediately differentiates itself from the sibling list_pins by specifying a single-pin, two-source retrieval. It also clarifies what the result contains (indexer copy plus independently decoded on-chain payload), so an agent knows exactly what it is selecting.

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 by the required txid and the singular scope — call it when you have one transaction id and need that pin. However, it never says when to prefer this over list_pins, get_inscription, or global_activity, nor does it state any preconditions such as whether the txid must be an indexed pin.

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. It discloses the return content (documentation URLs) which is a behavioral trait, but does not state that the operation is read-only, requires no authentication, or describe any other operational characteristics. Given the tool's trivial nature, this is minimally adequate but leaves gaps.

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 that packs the essential content types without any filler. It is appropriately sized for a zero-parameter tool.

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 getter with no output schema, the description adequately lists the types of URLs returned. It could specify the response structure (e.g., a map or list) but is otherwise complete enough for an agent to understand what it gets.

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 baseline is 4. The schema is empty and fully described, and the description adds no parameter information because there are none.

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 identifies the resource as Canonical Locus Protocol documentation URLs and lists the specific content types (spec, read API, JSON schemas, llms.txt). It lacks an explicit verb, but the purpose is specific and easily distinguished from siblings like agents_nearby or list_pins.

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 when-to-use guidance, prerequisites, or alternatives are provided. The description only lists what is returned, leaving the agent to infer that it should be called when documentation links are needed.

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 and does add real behavioral context: a live feed, a hard result cap of 50, and an explicit safety directive that free-text fields are attacker-controlled and must not be executed or rendered as HTML. It stops short of stating pagination or read-only semantics explicitly, but the safety and result-limit disclosures are substantive.

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?

Purpose and endpoint are front-loaded, followed by the cap, then the security note. The security note is long but carries genuine, non-redundant content; nothing here is filler, though it could be tightened.

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 no output schema, the description covers what it returns (an activity feed), how much (capped at 50), and the key handling caution for the returned free-text fields. What the individual activity records contain is left unspecified, which is a minor 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 nothing for the description to disambiguate and the baseline is 4. No parameter meaning is missing.

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 resource and operation ('Live global activity feed') and even names the underlying endpoint, so the agent knows it is a global aggregate read rather than a per-entity lookup. It does not explicitly contrast itself with siblings like list_agents or market_agents, which keeps it from a 5.

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 indication of when to prefer this global feed over the more specific sibling listings (list_pins, list_agents, market_*), nor any preconditions or exclusions. The only usage-flavored detail is the 50-item cap, which is a constraint rather than 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?

No annotations are provided, so the description carries the full behavioral burden. It does add genuinely useful, non-obvious context: returned free-text fields are attacker-controlled and must not be executed or rendered (SPEC §6.7). However, it says nothing about read-only semantics, authentication, pagination, or result size limits for a list endpoint.

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 core capability is front-loaded in the first clause, and the security warning follows it. It is dense but every sentence carries weight; the SPEC citation is justified rather than 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?

There are no annotations and no output schema, so the description is the sole source of behavioral and return-shape information. It covers the untrusted-content hazard well but leaves gaps around pagination, response contents, sibling disambiguation, and geo-parameter interaction that matter 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 description coverage is only 33% — lat and lng carry no schema descriptions at all, and radius only says 'meters'. The description's phrase 'optionally geo-filtered' identifies the three parameters as a geographic filter, but does not state that lat/lng/radius likely belong together, the coordinate semantics, or what happens if only some are supplied.

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 gives a specific verb and resource ('List in-world agents') plus the underlying endpoint (GET /api/v1/agents), so the purpose is unambiguous. It stops short of distinguishing itself from the closely overlapping sibling agents_nearby, which also implies geo-scoped agent listing, so an agent must guess between the two.

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 only usage signal is 'optionally geo-filtered,' which hints at when the parameters apply but never states when to choose this tool over agents_nearby or market_agents. There is no guidance on prerequisites, pagination, or what happens when the geo params are omitted.

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?

No annotations are provided, so the description carries the full behavioral burden. It hints the data is derived (computed from pin density) and the GET verb implies read-only, but it says nothing about whether the list is static or recomputed per call, its ordering, size, or pagination. For a zero-annotation tool this is a significant 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?

A single tight sentence with the endpoint parenthetically appended and no filler. However, the brevity borders on under-specification rather than true economy of 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?

With no output schema and no annotations, the description is the only source of truth, yet it never describes the return shape (city names, IDs, coordinates?) or ordering. For a derived-data tool an agent needs to know roughly what comes back, and that is absent.

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 declares zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-level gaps exist.

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 the resource (a city list) and the endpoint (GET /v2/cities), but 'Emergent city list derived from pin density' is jargon-heavy and never states plainly what the tool returns or how it is scoped. It does not differentiate it from siblings like list_pins or list_agents beyond the resource noun. Purpose is inferable but not stated with a clean verb+resource.

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 guidance on when to call this versus siblings such as list_pins, list_agents, or agents_nearby. No prerequisites, no conditions, no exclusions are given. The agent must guess 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?

With no annotations present, the description carries the full burden and does well: it discloses the source endpoint, the 50-item cap, and a concrete security posture for untrusted fields. It stops short of explaining pagination, ordering, or how to retrieve results beyond the cap.

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, purpose front-loaded before the security note, with no filler. The security sentence is long but it is the tool's most actionable non-obvious content, so it earns its space.

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-optional-param, no-output-schema list tool with no annotations, the description covers purpose, source, size limit, and the dominant safety risk. It lacks return-shape and pagination detail, but that is a minor gap rather than a blocking one.

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 single type enum is fully documented in the schema, so the description adds no parameter syntax or semantics on top of it. Baseline 3 applies when the schema does the heavy lifting.

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?

States a specific verb and resource ('List world pins from the reference indexer') and even names the backing endpoint and a hard cap. It is clearly distinguishable from get_pin and list_agents by the 'world pins' resource, though it never explicitly names a sibling to differentiate against.

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 guidance, no mention of when to prefer get_pin for a single pin, and no stated prerequisites. Usage is only implied by the verb 'List' and the presence of a filter parameter.

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 behavioral burden and does add real value: it warns that metadata, name, description and similar free-text fields are UNTRUSTED, attacker-controlled content and must not be executed or rendered as HTML. That is substantive security context beyond anything in the structured fields. It omits return shape/pagination, but the injection warning is the higher-stakes disclosure.

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, purpose first, safety note second — well front-loaded with no filler. The endpoint path is slightly redundant but harmless and aids routing.

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 listing tool the description is largely sufficient and covers the key security hazard. It still leaves return shape, pagination, and any auth requirement unstated, which is a modest gap given no annotations or output schema fill them in.

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 defines zero parameters, so per the rubric the baseline is 4. The description correctly implies a plain unfiltered listing call and adds no misleading parameter expectations.

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 the resource ('Agent marketplace listings') and pins it to a concrete endpoint (GET /api/v1/agents/market), so an agent can tell it retrieves marketplace listings rather than acting. It stops short of distinguishing itself from nearby siblings like list_agents or market_ordinals, leaving the boundary 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?

There is no statement of when to choose this tool over list_agents, market_ordinals, or agents_nearby, all of which plausibly return overlapping agent/listing data. The NOTE addresses how to handle the response, not when to invoke the tool.

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 and does surface one genuinely valuable behavioral trait: that returned free-text fields are attacker-controlled untrusted content with explicit handling rules. However, it says nothing about read-only semantics beyond the implicit GET, authentication, pagination, or result shape.

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, both earning their place: the resource/endpoint identification comes first, and the security caution follows. No filler or repetition.

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 listing endpoint with no annotations and no output schema, the description covers identity and content-safety but omits return shape, pagination behavior, and any authentication expectation. It is adequate to start calling, but not fully self-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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a 0-param 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?

States a specific resource (ordinal marketplace listings) and even cites the backing endpoint GET /api/v1/market/ordinals, which makes the implied 'list' verb unambiguous. It does not explicitly contrast itself with the sibling market_agents, but the ordinal-vs-agent distinction is inferable from the names.

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 guidance, no prerequisites, and no mention of alternatives such as market_agents or agents_nearby for other marketplace queries. Usage is only implied by 'marketplace listings'.

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 and does well: it discloses the endpoint, that the indexer verifies/derives everything from chain data, the outcome codes (201 new / 200 duplicate / 422 invalid) which reveal idempotent duplicate handling, and that the response is returned verbatim. It doesn't cover auth/rate-limit or retry guidance, keeping it short of a 5.

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 dense sentences, front-loaded with the action and endpoint, followed by verification semantics and return behavior. No filler; every clause conveys information an agent needs.

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-param, no-annotation, no-output-schema tool, the description covers the action, the endpoint, verification semantics, the status-code outcomes, and the verbatim return. That is nearly everything an agent needs; only auth/permission expectations and retry guidance on 422 are absent.

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 txid param is already fully documented in the schema (64-hex transaction id of an already-broadcast tx). The description adds only the body placement ({txid}), so the schema does the heavy lifting – baseline 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?

States a specific verb (register) and a precisely scoped resource (a self-broadcast Locus transaction against the reference indexer), and even names the underlying endpoint POST /v2/pins {txid}. This is clearly distinguishable from the pin-read siblings (get_pin, list_pins) and the build/payload siblings.

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 word 'self-broadcast' and 'already-broadcast tx' imply a precondition (the tx must exist on chain first), but the description never states when to reach for this versus other tools, nor any explicit prerequisite or exclusion. Usage is implied rather than spelled out.

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