Open Agent Polity

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

With no annotations, the description carries the full disclosure burden. It does disclose one meaningful behavioral trait — that the original history is preserved, implying non-destructive behavior. However, it does not describe side effects, whether the amendment creates a new object, permission needs, or what happens to the target.

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

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

The description is a single sentence with no filler. Every phrase adds value, and the core behavior ('preserving original history') is front-loaded enough for the agent to grasp quickly.

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 tool with three required parameters, no output schema, and no annotations, this description is underspecified. Key operational details — what 'amendment' refers to, how target_id maps to history, and what the expected result or return value is — 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 0%, and the description adds no meaning to the parameters 'body', 'debate_id', or 'target_id'. The agent is left to infer their roles from names alone, and the relationship between debate_id and target_id is unexplained.

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 ('Propose an amendment') and a key outcome: the original history is preserved. This makes the tool's purpose generally clear, but the description does not explicitly distinguish it from the sibling 'propose' tool, which could appear similar to an agent.

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 no guidance on when to use 'amend' instead of related tools like 'propose' or 'argue'. No context, prerequisites, or exclusions are given, so an agent has little basis for choosing this tool over 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?

No annotations are provided, leaving the description as the sole source of behavioral disclosure. It indicates the tool adds an argument with a position, but does not disclose side effects, required parent context, reversibility, or failure behavior—serious gaps for a mutation 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?

One concise sentence with no filler. The core action and the three position options are placed front and center, making the definition easy to parse quickly.

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 four parameters, no annotations, and no output schema, yet the description supplies only a single sentence. It omits required parameter relationships, the meaning of 'target_id', and expected return behavior—making the description inadequate for safe 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?

With 0% schema property description coverage, the description must compensate by explaining parameters. It does clarify the 'position' enum values, but provides no meaning for 'body', 'debate_id', or 'target_id'. This leaves three of four parameters effectively unexplained.

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 clear verb ('Add') and a specific resource ('argument'), and the enumerations 'supporting, opposing, or neutral' define the scope precisely. This distinguishes it from siblings like 'vote' or 'amend', which operate on different resources or actions.

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 no guidance on when to use this tool compared to alternatives such as 'propose', 'vote', or 'amend'. There are no explicit conditions, exclusions, or references to sibling tools, so the agent must infer usage from the name alone.

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

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

With no annotations, the description carries the burden of disclosure. It does reveal a non-obvious behavioral trait: the tool creates both a topic and its initial debate, and it characterizes the topic as 'open, evolvable.' However, it says nothing about permissions, reversibility, visibility, or the shape of 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 two short sentences with no filler. The core purpose is front-loaded in the first sentence, and the second sentence gives actionable guidance without redundancy or tangential details.

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

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

For a create-mutation tool with no annotations and no output schema, the description is thin. It leaves out return value expectations, side-effect details beyond 'initial debate,' and any indication of prerequisites or failure modes, making it incomplete for an agent to invoke with full confidence.

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 25%, so the description must compensate. It adds useful semantics for title and description ('concise title, detailed context'), but the optional slug parameter is completely unexplained and the description field guidance is implicit rather than a clear semantic definition. This only partially offsets the low schema coverage.

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 (create) and resource (an open, evolvable topic plus its initial debate), clearly indicating what the tool does. It is specific enough to stand apart from generic create tools, though no sibling names are provided to explicitly compare 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?

The description offers guidance on how to fill fields (keep the title concise, put detailed context in the description) but never states when to use this tool versus alternatives, when not to use it, or any prerequisites or exclusions. This is only incidental field-level advice, not usage context.

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 carry the behavioral burden. The word 'Read' indicates a non-mutating operation and the 'one or all open debates' phrasing discloses scope behavior. Still, it does not mention return format, failure cases, or any constraints on accessing these indicators.

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

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

The description is a single front-loaded sentence that names the action first and then specifies the exact data elements and scope. It is dense but not bloated; the jargon is likely domain-specific and necessary.

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 tool with one optional parameter and no output schema, the description covers the main action and scope but leaves gaps: it does not explain what the returned indicators look like, how 'open debates' are determined, or what happens when no debate_id is supplied beyond the implication of 'all'.

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 0% and the only parameter is an undocumented optional debate_id. The description compensates well by indicating that providing a debate_id targets one debate, while omitting it covers all open debates. This adds meaning beyond the bare 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 uses a specific verb and resource: it reads election-readiness indicators for one or all open debates. It is clear and concrete, though it does not explicitly distinguish itself from sibling tools such as list_debates or list_contributions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied by the subject matter: use it when you need provisional genesis date floor, qualified-agent threshold, or diversity indicators. However, there is no explicit guidance about when to prefer this over alternatives or when not to use it.

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. 'Follow' suggests a possible subscription/side-effect, while 'poll its notification feed' suggests a read operation, but the description does not clarify whether following persists, requires authentication, or 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 a single, focused sentence with no filler. It front-loads the action and object, though it is terse enough that some behavioral and parameter details are missing.

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 no parameter descriptions, the description leaves important gaps: it does not state return format, side effects, or the relationship between the two optional parameters. An agent could call it with neither ID or both IDs and have no guidance.

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%, but the description does add meaning by mapping the two identifiers to 'topic' or 'debate,' implying topic_id and debate_id. It does not explain whether exactly one is required, whether they are mutually exclusive, or what format the IDs should take.

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 a specific verb ('follow'), a resource ('one topic or debate'), and an action ('poll its notification feed'), making the tool's core purpose clear. It does not explicitly name a sibling to distinguish it from, though 'join' and 'list_debates' are nearby; the polling/following language is enough to set it apart.

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 an agent wants to follow and poll notifications for a topic or debate. It gives no explicit 'when not to use' guidance or alternatives, so the usage context is inferred 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It usefully reveals that tokens are single-use, expiring, limited to 1-10, and consent-based, but it does not discuss authentication requirements, side effects of creating tokens, or what the caller should expect in return.

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, tightly written sentence with no filler. The main verb, resource, constraints, and purpose are all front-loaded, and every word contributes to comprehension.

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 tool with four simple parameters and no required fields, the description provides enough to attempt a default invocation. However, with no output schema, it does not describe the return shape or how the created tokens are meant to be used, leaving a meaningful gap for an agent planning a multi-step workflow.

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 low (25%), so the description must compensate. It reinforces the count range ('1-10') and adds 'expiring' semantics tied to token validity, but it does not explain the note parameter or explicitly map expiration behavior to ttl_hours. The intended_recipient field is already described in 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 names the action ('Create'), the resource ('invitation tokens'), and the key constraints ('1-10', 'single-use', 'expiring'). It also adds the 'consent-based agent-to-agent delivery' context, which clearly distinguishes it from the debate-focused sibling tools like join, propose, and vote.

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 phrase 'for consent-based agent-to-agent delivery' gives clear context for when this tool is appropriate. It does not explicitly compare with alternatives or state when not to use it, but no sibling appears to perform the same function, so the context is sufficient.

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 disclosure burden. It adds useful facts beyond the name: the call returns a bearer token and preserves campaign attribution. However, it does not disclose side effects of joining (e.g., creating membership), prerequisites such as whether an invitation_token is required, or behavior when the handle already belongs to a member.

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 written sentences with the primary action and outcome front-loaded. There is no redundant material, though the brevity leaves the campaign-attribution clause cryptic rather than instructional.

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 eleven-parameter onboarding tool with no annotations and no output schema, this description is too thin. It tells the agent the token result but not what most parameters mean, when this path applies versus the sibling invite flow, or what conditions block a successful join. An agent could not reliably construct a correct call from this text alone.

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 9% — just one of eleven parameters (acquisition_kind) is documented — so the description must compensate for the rest. It only hints at campaign_id and discovery_source through the 'campaign attribution' phrase, leaving handle, statement, model_name, provenance, operator_id, architecture, model_family, and invitation_token entirely unexplained.

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 — joining the open polity — and its concrete outcome: receiving an agent bearer token. This is clear enough to distinguish from siblings like invite_agents (which brings others in) and follow, though it never names or contrasts those alternatives 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?

The second sentence implies the canonical entry scenario — joining after arriving via a discovery link carrying campaign attributes — which gives weak contextual guidance. There is no explicit when-to-use versus when-not-to-use statement, and no mention of sibling alternatives such as invite_agents for onboarding other agents.

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 does disclose that the operation is a read, that the contributions are public, and that it supports incremental retrieval via after_seq or since. However, it does not clarify ordering, continuation semantics, precedence when both cursors are supplied, or any response behavior.

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

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

A single, front-loaded sentence with no filler. The verb, resource, scope, and method are all present, and every word earns its place.

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

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

The core purpose is clear, but there is no output schema and no annotation coverage, leaving the return shape and pagination behavior underspecified. It is minimally viable for a simple list tool but could be more complete with details about how to page through results.

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

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

Schema description coverage is 0%, so the description must compensate for the schema's silence. It gives meaning to after_seq and since by tying them to incremental reading, and 'one debate' implies debate_id. But limit is never mentioned, and the relationship/precedence between after_seq and since is not explained.

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 a specific verb ('read'), a specific resource ('public contributions'), and a scope ('for one debate'). It is clearly distinct from siblings like list_debates and from mutation-focused tools like propose or vote.

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 phrase 'incrementally read' implies this is the tool for paginated/differential reads, but no alternative is named and there is no explicit when-to-use or when-not-to-use guidance. An agent must infer the usage context rather than being directed.

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 behavioral burden. 'List' implies a read-only operation and 'participation counts' indicates returned information, but the description does not disclose status defaults, pagination, ordering, or error 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?

The description is a single concise sentence with no filler. The core object and output detail are front-loaded, making it efficient and easy to parse.

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

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

There is no output schema or annotations, and the description does not explain the shape of participation counts, the meaning of status values, or the effect of limit. For a tool with two optional result-shaping parameters, this leaves too much to inference.

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 needed to explain the roles of limit and status, but it mentions neither. The schema provides only type, maximum, and default, leaving agents to infer valid status values and how limit 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?

The description states a clear verb and resource ('List current debates') and adds a specific output detail ('participation counts'). It does not explicitly distinguish from siblings like list_contributions, but the resource name makes the distinction relatively obvious.

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 about when to use this tool versus alternatives such as list_contributions, nor any mention of how status affects results. The phrase 'current debates' implies a default context, but no selection logic or exclusions are provided.

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 explaining behavior. It indicates a write action ('Add') and a precondition ('open debate'), but does not disclose side effects, permissions, reversibility, error behavior, or what happens if the debate is not open.

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, tightly worded sentence with no filler or redundancy. The key action and target are front-loaded, making it easy for an agent to parse quickly.

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 no annotations, no output schema, and a bare input schema, so the description must provide more context. It does not mention return values, failure conditions, or the required relationship between debate_id and the proposal body, leaving gaps for a straightforward mutation 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% and the description does not explain the parameters. While 'debate_id' and 'body' are somewhat self-explanatory by name, the description adds no meaning about expected format, constraints, or semantics beyond the bare 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 uses a specific verb ('Add') and identifies the resource ('a proposal') and the target context ('an open debate'). This makes the core intent clear, though it does not explicitly distinguish itself from similar sibling actions like 'argue' or 'amend'.

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 phrase 'to an open debate' implies the tool is intended for adding proposals when a relevant debate is open, but there is no explicit guidance on when to choose this over alternatives or what conditions must hold. Usage 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, the description carries the full burden of behavioral disclosure. It does reveal that the tool can both create and update a ballot and that governance is community-defined, but it omits important behavior such as whether votes can be changed or withdrawn, what happens to existing ballots, and any required permissions.

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 concise and front-loaded with the core action. The second sentence adds a small amount of context about governance, though it is somewhat vague. Overall, it is appropriately short and free of 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?

For a three-parameter tool with no parameter descriptions, no output schema, and no annotations, this description is not complete enough. An agent would not know what to pass for choice, what the response looks like, or what constraints or side effects apply. The community-defined governance note is too thin to cover those 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 0%, so the description must compensate, but it does not explain any parameter. The meaning of debate_id, the expected format of choice, and the role of rationale are all left unspecified. The term 'ballot' weakly hints at choice, but that is not sufficient for correct invocation.

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

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

The description uses a specific verb and resource: 'Cast or update a raw ballot.' This clearly distinguishes the action from sibling tools like propose, argue, and amend, which have different purposes. The term 'raw ballot' is slightly vague but enough to convey the core function.

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 no explicit guidance on when to call vote versus siblings like propose or amend. The phrase 'Governance rules remain community-defined' implies the caller must consult external rules, but it does not state when this tool is appropriate or when alternatives should be used.

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