map_relationships

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 states what the tool reveals (relationships) but does not mention whether it is read-only, whether it has side effects, or what the output format looks like (e.g., list, graph, summary). It does not disclose any limitations or performance characteristics. The description gives a functional overview but omits behavioral traits that would be important for an agent to predict side effects or interpret results.

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 exactly two sentences, front-loading the primary action ('Map the dependency and ownership relationships') before adding clarifying details. Every clause earns its place—the second sentence specifies what is shown and why it is useful. There is no redundant wording or excessive length, making it efficient and easy to scan.

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 that maps a potentially complex graph of relationships, the description is minimal. It lacks any indication of the output structure (e.g., does it return a list, a tree, a diagram?), which would be crucial for an agent to know how to consume the result. It also does not clarify whether the output is limited to direct relationships or includes transitive ones, nor does it specify the level of detail. Given that there is no output schema and no annotations, the description should have compensated with more detail about expected results, but it does not. This leaves the agent with an incomplete picture.

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 already documents the single optional parameter 'contract' with 100% coverage, explaining that omitting it maps all contracts. The description itself does not add any further parameter-level guidance—it never mentions the parameter. Since the schema fully covers the parameter semantics, the description earns the baseline score of 3; it neither adds nor detracts from what is already documented.

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 'Map' and the specific resource: 'dependency and ownership relationships between Dysnomia contracts.' It elaborates with concrete details ('which contracts own, mint for, or reference each other') and gives a practical use case ('useful for understanding the ecosystem graph'). This distinguishes it from siblings like list_ecosystem (which likely lists contracts) and get_contract_state (which fetches state), so purpose is 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 description provides some context ('useful for understanding the ecosystem graph') but does not explicitly state when to use this tool versus alternatives. It does not mention when not to use it or point to sibling tools. While the focus on relationships is implied, there is no explicit routing guidance, leaving the agent to infer its niche among the listed siblings.

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