Agent Record

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 makes the read-only nature explicit ("Read"), and since there is no output schema it usefully previews the returned content — status counts, median latency, and the count of untestable registry entries. It does not cover scoping (which agents/tools are counted) or whether the census is historical or point-in-time, but the essential behavior is disclosed.

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 compact sentences: the payload description is front-loaded, and the default-behavior note follows. Every clause adds information; nothing is padding.

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-optional-parameter, read-only tool with no output schema, the description is nearly sufficient — it explains both the input default and the shape of the result. A brief note on what population the census covers (all agents vs. a workspace) is the only meaningful omission.

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 only parameter's format (YYYY-MM-DD) is already documented, so the baseline would be 3. The description adds genuine meaning beyond the schema by stating that day defaults to the latest, which the schema does not say and which changes how an agent may call it.

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?

"Read the dated census of working agents and tools" gives a specific verb plus resource, and the enumeration of aggregates (counts by status, median latency, untestable entries) clearly separates it from per-record siblings like agentrecord_lookup and agentrecord_search. It stops short of naming those siblings explicitly, so the differentiation is implied rather than stated.

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 versus agentrecord_lookup, agentrecord_search, or the mutating siblings. Aggregate/overview usage is only weakly implied by the word "census", and no exclusions or prerequisites 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 burden and mostly succeeds: it enumerates exactly what is returned (census response and latency/streak, tool listing, delivered rate, 95% lower bound, independent issuer count, confidence), names the data provenance (daily census, signed receipts), and discloses the commercial model ('Free; no paid placement'). It does not say what happens for an unknown target or whether calls are rate-limited, so it is not fully 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?

Three sentences with the action directive front-loaded, then the return payload, then the no-paid-placement caveat. Dense but every clause adds information; only the parenthetical '(and how fast, how many days in a row)' is slightly padded phrasing.

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 read tool with no output schema, the description effectively stands in for a return-value spec by naming the fields an agent will get back. The remaining gap is edge-case behavior (unknown/unreachable target) which matters for a lookup whose whole purpose is judging availability.

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 'target' parameter is already documented with the same examples (endpoint URL, registry name, agent id). The description restates those accepted forms but adds no format syntax, normalization rules, or fallback behavior beyond the schema, so 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+resource: look up an agent or tool's record (census presence, tool listing, delivery/receipt stats) from its endpoint URL, registry name or id. An agent can tell this is a reputation/health lookup rather than the sibling census or search tools, though it never names those siblings 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?

Gives an explicit trigger: 'Use before you pick or call an agent or tool you have not used.' That is clear when-to-use guidance. It stops short of stating when NOT to use it or naming agentrecord_search/census as the alternative for discovery, so it lands at 4 rather than 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?

No annotations are provided, so the description carries the full behavioral burden. It implies an asynchronous path ('tomorrow's census') and states URL eligibility, but says nothing about idempotency, authentication needs, whether nominations are publicly visible, or what happens when a URL fails validation — all material for a submission 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 short sentences with the purpose first and the eligibility restriction second; no filler, and the most important constraint is not buried.

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 two-parameter submission tool with no annotations and no output schema, the definition covers intent and eligibility but omits outcome and failure behavior. It is minimally sufficient to attempt correct invocation, not to predict the result.

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

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

Schema description coverage is 0%, so the description must compensate. It meaningfully qualifies the required `url` parameter (public, http(s), ports 80/443), but the `kind` parameter is never mentioned beyond the enum being self-explanatory; partial compensation only.

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 ('ask ... to be added') and resource ('public MCP or A2A endpoint'), plus the destination ('tomorrow's census'), so the action is unambiguous. It does not explicitly contrast itself with siblings like agentrecord_submit_receipt or agentrecord_census, leaving that 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?

Useful eligibility constraints are stated ('Only public http(s) URLs on ports 80/443'), which tell the agent when a nomination is valid. However, there is no guidance on when to nominate versus consult agentrecord_census or agentrecord_lookup, nor on whether repeat nominations are allowed.

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 exist, so the description must carry the full behavioral load. It usefully discloses the fixed sort order (text match, census status, 30-day working share, name) and that ranking cannot be bought, which is real transparency about result ordering. It says nothing about pagination, result volume, auth, or rate limits, and no output schema exists to fill that 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 tight sentences, front-loaded with the action and resource, with no filler. The ranking sentence earns its place because ordering is non-obvious, though it could be trimmed slightly.

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 annotations, no output schema, and 0% parameter coverage, the description would need to explain the status enum values, what 'limit' controls, and roughly what a result row contains. None of that is present, leaving significant gaps for a three-parameter search 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 0% for three parameters, and the description only implicitly covers 'q' as 'keyword'. The eight-value status enum (working, protocol_only, auth_required, rate_limited, alive_not_mcp, gone, down, error) is never explained, and 'limit' is unmentioned entirely. Worse, 'Find working agents' implies a working-only scope while the enum admits gone/down/error, which could mislead an agent about what status does.

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 ('Find working agents and tools by keyword') plus the data source ('latest daily census'), so the agent knows exactly what this searches. It does not name the sibling tools (agentrecord_census, agentrecord_lookup) to sharpen the boundary, 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?

'by keyword' implies a search-style query, but there is no explicit statement of when to choose this over agentrecord_lookup or agentrecord_census, and no prerequisites or exclusions. Usage is inferable but never 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, the description carries the full burden and does cover the important non-obvious behaviors: the payload must be signed with the caller's own ed25519 key, the format lives at /v1/method, and receipts are de-duplicated by distinct issuer. It omits what happens on repeated submissions (idempotency), whether receipts are mutable, and what a successful call returns, which matters for an unannotated write 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?

Four tight sentences with the core operation front-loaded, followed by signing detail, the counting rule, and the alternate mode. No filler, though the ordering puts the less critical 'anyone may submit' note ahead of the more important signing format pointer.

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 an unannotated, three-parameter write tool with nested objects and no output schema, the description leaves too many holes: subject_id is undefined, required-vs-optional combinations between receipt and countersign_stamp are not explained, and the agent is not told what a success response looks like. The /v1/method pointer helps, but it delegates essential schema knowledge outside the definition.

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 only 33%, so the description must compensate. It adds real meaning for countersign_stamp (a way to record a Countersign verdict) and clarifies that receipt must be a signed v=1 payload pointing to /v1/method. subject_id is left entirely unexplained in both schema and description, which is a genuine 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?

The opening sentence gives a specific verb and resource ('Record that a tool or agent did... a piece of work') and makes the success/failure scope explicit. It is clearly the write-side sibling to census/lookup/search, but it never names those tools, so differentiation is by implication rather than statement.

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 says 'Anyone may submit' and that receipts 'are counted by distinct issuer so one source cannot dominate', which tells the agent the access model and a scoring rule. It also flags a second usage mode via countersign_stamp. However, it never says when to use this versus agentrecord_lookup or agentrecord_nominate, nor what prerequisites must exist before submitting a receipt.

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